---
title: Dataset
seo:
  title: Dataset — Python SDK
  description: >-
    A schema-enforced collection of `Example` objects on the Judgment platform.
    (Python SDK)
description: A schema-enforced collection of `Example` objects on the Judgment platform.
---

Datasets are created and retrieved via `client.datasets`. Every
dataset has a JSON Schema that all examples are validated against
server-side. Once you have a `Dataset`, you can append examples, add
trace-backed examples, list versions, iterate over examples, export
to JSON/YAML, or display a rich table preview.

Create a dataset and add examples:

```python
dataset = client.datasets.create(
    name="golden-set",
    schema={
        "type": "object",
        "properties": {
            "input": {"type": "string"},
            "expected_output": {"type": "string"},
        },
    },
)
dataset.add_examples([
    Example.create(input="What is AI?", expected_output="Artificial Intelligence"),
])
```

Retrieve and iterate:

```python
dataset = client.datasets.get(name="golden-set")
for example in dataset:
    print(example["input"])
```

## Attributes

| Prop | Type | Default | Description |
| - | - | - | - |
| `name?` | `str` | - | Dataset name. |
| `project_id?` | `str` | - | Owning project ID. |
| `project_name?` | `str` | - | Project name. |
| `dataset_id?` | `Optional[str]` | `None` | Unique dataset identifier (set when created/fetched). |
| `schema?` | `Optional[Dict[str, Any]]` | `field(default=None)` | The dataset's JSON Schema. Examples must conform to it. |
| `current_version?` | `Optional[int]` | `None` | Latest dataset version number. |
| `dataset_kind?` | `str` | `'example'` | Kind of dataset (default "example"). |
| `examples?` | `Optional[List[Example]]` | `None` | The loaded examples (populated when using .get()). |
| `client?` | `Optional[JudgmentSyncClient]` | `None` | Internal API client (set automatically). |

***

## add\_from\_json()

Upload examples from a JSON file.

The file should contain a JSON array of objects, where each object
has the fields you want as example properties (e.g. `input`,
`actual_output`, `expected_output`).

```python
dataset.add_from_json("./data/golden-set.json")
```

```python
def add_from_json(file_path, batch_size=100) -> None:
```

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `file_path` | `str` | - | Path to the JSON file. |
| `batch_size?` | `int` | `100` | Number of examples uploaded per API call. |

### Returns

`None`

***

## add\_from\_yaml()

Upload examples from a YAML file.

Same as `add_from_json` but reads YAML format.

```python
def add_from_yaml(file_path, batch_size=100) -> None:
```

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `file_path` | `str` | - | Path to the YAML file. |
| `batch_size?` | `int` | `100` | Number of examples uploaded per API call. |

### Returns

`None`

***

## add\_examples()

Append `Example` objects to this dataset.

Examples are validated server-side against the dataset schema and
uploaded in batches with a progress bar. Each successful batch
advances the dataset version. Accepts any iterable, including
generators.

**TypeError**: If a single `Example` is passed instead of a list.
**JudgmentValidationError**: If examples fail schema validation.

```python
def add_examples(examples, batch_size=100) -> None:
```

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `examples` | `Iterable[Example]` | - | A list (or iterable) of Example objects. |
| `batch_size?` | `int` | `100` | Number of examples per upload batch. |

### Returns

`None`

***

## versions()

List all versions of this dataset, newest first.

```python
def versions() -> typing.List:
```

### Returns

`typing.List` - A list of `DatasetVersion` objects.

***

## delete()

Delete this dataset from the platform.

Dependent test configs are deleted along with the dataset.

```python
def delete() -> None:
```

### Returns

`None`

***

## save\_as()

Export the dataset to a local JSON or YAML file.

```python
dataset = client.datasets.get(name="golden-set")
dataset.save_as("json", dir_path="./exports")
```

```python
def save_as(file_type, dir_path, save_name=None) -> None:
```

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `file_type` | `Literal['json', 'yaml']` | - | "json" or "yaml". |
| `dir_path` | `str` | - | Directory to write into (created if it doesn't exist). |
| `save_name?` | `Optional[str]` | `None` | File name without extension. Defaults to a timestamp. |

### Returns

`None`

***

## display()

Print a formatted table preview to the terminal.

```python
def display(max_examples=5) -> None:
```

### Parameters

| Prop | Type | Default | Description |
| - | - | - | - |
| `max_examples?` | `int` | `5` | Maximum number of examples to show. |

### Returns

`None`