> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/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.
</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>]
```

| Option     | Description                                       |
| ---------- | ------------------------------------------------- |
| `--space`  | Filter by space name or ID                        |
| `--name`   | Case-insensitive substring filter on dataset name |
| `--limit`  | Maximum number of results to return (default: 15) |
| `--cursor` | Pagination cursor for the next page               |

**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>)
```

| Option    | Description                                                                    |
| --------- | ------------------------------------------------------------------------------ |
| `--name`  | Name for the new dataset                                                       |
| `--space` | Space name or ID to create the dataset in                                      |
| `--file`  | Path to the data file (CSV, JSON, JSONL, or Parquet), or `-` for stdin         |
| `--json`  | Inline JSON array of examples, e.g. `'[{"question": "...", "answer": "..."}]'` |

**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>]
```

| Option    | Description                                                         |
| --------- | ------------------------------------------------------------------- |
| `--space` | Space name or ID (required when using a dataset name instead of ID) |

**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>]
```

| Option    | Description                                                         |
| --------- | ------------------------------------------------------------------- |
| `--name`  | New name for the dataset                                            |
| `--space` | Space name or ID (required when using a dataset name instead of ID) |

**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` | Space name or ID (required when using a dataset name instead of ID) |
| `--force` | Skip the confirmation prompt                                        |

**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`      | 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             |

**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>]
```

| Option         | Description                                                                    |
| -------------- | ------------------------------------------------------------------------------ |
| `--json`       | Inline JSON array of examples, e.g. `'[{"question": "...", "answer": "..."}]'` |
| `--file`       | Path to the data file (CSV, JSON, JSONL, or Parquet), or `-` for stdin         |
| `--space`      | Space name or ID (required when using a dataset name instead of ID)            |
| `--version-id` | Dataset version to append to (default: latest version)                         |

**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`  | Path to a file containing annotation records (JSON, JSONL, CSV, Parquet), or `-` for stdin |
| `--space` | Space name or ID (required when using a dataset name instead of ID)                        |

**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
```