> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Datasets

> Manage datasets with the AX CLI

<Note>
  The `ax datasets` commands are currently in **BETA**. The API may change without notice. A one-time warning is emitted on first use. The `update` command is in **ALPHA**.
</Note>

The `ax datasets` commands let you create, retrieve, and manage datasets on the Arize platform. Supported file formats: CSV, JSON, JSON Lines, Parquet.

## `ax datasets list`

List all datasets in a space.

```bash theme={null}
ax datasets list [--space <id>] [--name <filter>] [--limit <n>] [--cursor <cursor>] [--output <fmt>]
```

| Option            | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| `--space`, `-s`   | Filter by space name or ID                                     |
| `--name`, `-n`    | Case-insensitive substring filter on dataset name              |
| `--limit`, `-l`   | Maximum number of results to return (default: 15)              |
| `--cursor`, `-c`  | Pagination cursor for the next page                            |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path |
| `--verbose`, `-v` | Enable verbose logs                                            |

**Examples:**

```bash theme={null}
ax datasets list --space sp_abc123
ax datasets list --space sp_abc123 --output datasets.json
```

## `ax datasets create`

Create a new dataset from a local file.

```bash theme={null}
ax datasets create --name <name> --space <id> (--file <path> | --json <json-array>) [--output <fmt>]
```

| Option            | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| `--name`, `-n`    | Name for the new dataset                                                       |
| `--space`, `-s`   | Space name or ID to create the dataset in                                      |
| `--file`, `-f`    | Path to the data file (CSV, JSON, JSONL, or Parquet), or `-` for stdin         |
| `--json`          | Inline JSON array of examples, e.g. `'[{"question": "...", "answer": "..."}]'` |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path                 |
| `--verbose`, `-v` | Enable verbose logs                                                            |

**Examples:**

```bash theme={null}
ax datasets create --name "my-eval-set" --space sp_abc123 --file ./examples.csv
ax datasets create --name "my-eval-set" --space my-space --json '[{"q": "What is AI?"}]'
```

## `ax datasets get`

Retrieve a dataset by name or ID.

```bash theme={null}
ax datasets get <name-or-id> [--space <id>] [--output <fmt>]
```

| Option            | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| `--space`, `-s`   | Space name or ID (required when using a dataset name instead of ID) |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path      |
| `--verbose`, `-v` | Enable verbose logs                                                 |

**Example:**

```bash theme={null}
ax datasets get ds_xyz789
ax datasets get my-eval-set --space my-space
```

## `ax datasets update`

Rename a dataset.

```bash theme={null}
ax datasets update <name-or-id> --name <new-name> [--space <id>] [--output <fmt>]
```

| Option            | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| `--name`          | New name for the dataset                                            |
| `--space`, `-s`   | Space name or ID (required when using a dataset name instead of ID) |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path      |
| `--verbose`, `-v` | Enable verbose logs                                                 |

**Examples:**

```bash theme={null}
ax datasets update ds_xyz789 --name "renamed-eval-set"
ax datasets update my-eval-set --space my-space --name "renamed-eval-set"
```

## `ax datasets delete`

Delete a dataset.

```bash theme={null}
ax datasets delete <name-or-id> [--space <id>] [--force]
```

| Option            | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| `--space`, `-s`   | Space name or ID (required when using a dataset name instead of ID) |
| `--force`, `-f`   | Skip the confirmation prompt                                        |
| `--verbose`, `-v` | Enable verbose logs                                                 |

**Examples:**

```bash theme={null}
ax datasets delete ds_xyz789
ax datasets delete my-eval-set --space my-space --force
```

## `ax datasets export`

Export examples from a dataset to a JSON file.

```bash theme={null}
ax datasets export <name-or-id> [--space <id>] [--version-id <id>] [--output-dir <path>] [--stdout] [--all]
```

| Option            | Description                                                         |
| ----------------- | ------------------------------------------------------------------- |
| `--space`, `-s`   | Space name or ID (required when using a dataset name instead of ID) |
| `--version-id`    | Export examples from a specific dataset version (default: latest)   |
| `--output-dir`    | Directory to write the output file (default: current directory)     |
| `--stdout`        | Print JSON to stdout instead of saving to a file                    |
| `--all`           | Use Arrow Flight for bulk export — streams all examples             |
| `--verbose`, `-v` | Enable verbose logs                                                 |

**Examples:**

```bash theme={null}
ax datasets export ds_xyz789
ax datasets export my-eval-set --space my-space --version-id v_123 --output-dir ./exports
ax datasets export ds_xyz789 --all
ax datasets export ds_xyz789 --stdout | jq 'length'
```

## `ax datasets append`

Append examples to an existing dataset. Provide examples via `--json` (inline) or `--file`. Exactly one input source is required.

```bash theme={null}
ax datasets append <name-or-id> (--json <json-array> | --file <path>) [--space <id>] [--version-id <id>] [--output <fmt>]
```

| Option            | Description                                                                    |
| ----------------- | ------------------------------------------------------------------------------ |
| `--json`          | Inline JSON array of examples, e.g. `'[{"question": "...", "answer": "..."}]'` |
| `--file`, `-f`    | Path to the data file (CSV, JSON, JSONL, or Parquet), or `-` for stdin         |
| `--space`, `-s`   | Space name or ID (required when using a dataset name instead of ID)            |
| `--version-id`    | Dataset version to append to (default: latest version)                         |
| `--output`, `-o`  | Output format (`table`, `json`, `csv`, `parquet`) or file path                 |
| `--verbose`, `-v` | Enable verbose logs                                                            |

**Examples:**

```bash theme={null}
# Append from a file
ax datasets append ds_xyz789 --file ./new_examples.csv

# Append inline JSON
ax datasets append ds_xyz789 --json '[{"question": "What is AI?", "answer": "..."}]'

# Append to a specific version
ax datasets append my-eval-set --space my-space --file ./more.jsonl --version-id v_123
```

## `ax datasets annotate-examples`

Annotate a batch of examples in a dataset. Provide annotations via `--file` (JSON, JSONL, CSV, or Parquet; use `-` for stdin). Each record must have a `record_id` (the dataset example ID) and `values` (a list of annotation dicts with at least `name`, plus optionally `score`, `label`, or `text`). Annotations are upserted; up to 1000 examples may be annotated per request.

```bash theme={null}
ax datasets annotate-examples <name-or-id> --file <path> [--space <id>]
```

| Option            | Description                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------ |
| `--file`, `-f`    | Path to a file containing annotation records (JSON, JSONL, CSV, Parquet), or `-` for stdin |
| `--space`, `-s`   | Space name or ID (required when using a dataset name instead of ID)                        |
| `--verbose`, `-v` | Enable verbose logs                                                                        |

**Examples:**

```bash theme={null}
ax datasets annotate-examples ds_xyz789 --file ./annotations.jsonl
ax datasets annotate-examples my-eval-set --space my-space --file ./annotations.json
```