/arize-dataset

name: arize-dataset
description: Creates, manages, and queries Arize datasets and examples. Covers dataset CRUD, appending examples, exporting data, and file-based dataset creation using the ax CLI. Use when the user needs test data, evaluation examples, or mentions create dataset, list datasets, export dataset, append examples, dataset version, golden dataset, or test set.
metadata:
  author: arize
  version: "1.0"
compatibility: Requires the ax CLI and a configured Arize profile.

Arize Dataset Skill

> **`SPACE`** — All `--space` flags and the `ARIZE_SPACE` env var accept a space **name** (e.g., `my-workspace`) or a base64 space **ID** (e.g., `U3BhY2U6...`). Find yours with `ax spaces list`.

Concepts

• **Dataset** = a versioned collection of examples used for evaluation and experimentation
• **Dataset Version** = a snapshot of a dataset at a point in time; updates can be in-place or create a new version
• **Example** = a single record in a dataset with arbitrary user-defined fields (e.g., `question`, `answer`, `context`)
• **Space** = an organizational container; datasets belong to a space

System-managed fields on examples (`id`, `created_at`, `updated_at`) are auto-generated by the server -- never include them in create or append payloads.

Prerequisites

Proceed directly with the task — run the `ax` command you need. Do NOT check versions, env vars, or profiles upfront.

If an `ax` command fails, troubleshoot based on the error:

• `command not found` or version error → see references/ax-setup.md
• `401 Unauthorized` / missing API key → run `ax profiles show` to inspect the current profile. If the profile is missing or the API key is wrong, follow references/ax-profiles.md to create/update it. If the user doesn't have their key, direct them to https://app.arize.com/admin > API Keys
• Space unknown → run `ax spaces list` to pick by name, or ask the user
• Project unclear → ask the user, or run `ax projects list -o json --limit 100` and present as selectable options
• **Security:** Never read `.env` files or search the filesystem for credentials. Use `ax profiles` for Arize credentials and `ax ai-integrations` for LLM provider keys. If credentials are not available through these channels, ask the user.

List Datasets: `ax datasets list`

Browse datasets in a space. Output goes to stdout.

ax datasets list
ax datasets list --space SPACE --limit 20
ax datasets list --cursor CURSOR_TOKEN
ax datasets list -o json

Flags

| Flag | Type | Default | Description | |------|------|---------|-------------| | `--space` | string | from profile | Filter by space | | `--limit, -l` | int | 15 | Max results (1-100) | | `--cursor` | string | none | Pagination cursor from previous response | | `-o, --output` | string | table | Output format: table, json, csv, parquet, or file path | | `-p, --profile` | string | default | Configuration profile |

Get Dataset: `ax datasets get`

Quick metadata lookup -- returns dataset name, space, timestamps, and version list.

ax datasets get NAME_OR_ID
ax datasets get NAME_OR_ID -o json
ax datasets get NAME_OR_ID --space SPACE   # required when using dataset name instead of ID

Flags

| Flag | Type | Default | Description | |------|------|---------|-------------| | `NAME_OR_ID` | string | required | Dataset name or ID (positional) | | `--space` | string | none | Space name or ID (required if using dataset name instead of ID) | | `-o, --output` | string | table | Output format | | `-p, --profile` | string | default | Configuration profile |

Response fields

| Field | Type | Description | |-------|------|-------------| | `id` | string | Dataset ID | | `name` | string | Dataset name | | `space_id` | string | Space this dataset belongs to | | `created_at` | datetime | When the dataset was created | | `updated_at` | datetime | Last modification time | | `versions` | array | List of dataset versions (id, name, dataset_id, created_at, updated_at) |

Export Dataset: `ax datasets export`

Download all examples to a file. Use `--all` for datasets larger than 500 examples (unlimited bulk export).

ax datasets export NAME_OR_ID
# -> dataset_abc123_20260305_141500/examples.json

ax datasets export NAME_OR_ID --all
ax datasets export NAME_OR_ID --version-id VERSION_ID
ax datasets export NAME_OR_ID --output-dir ./data
ax datasets export NAME_OR_ID --stdout
ax datasets export NAME_OR_ID --stdout | jq '.[0]'
ax datasets export NAME_OR_ID --space SPACE   # required when using dataset name instead of ID

Flags

| Flag | Type | Default | Description | |------|------|---------|-------------| | `NAME_OR_ID` | string | required | Dataset name or ID (positional) | | `--space` | string | none | Space name or ID (required if using dataset name instead of ID) | | `--version-id` | string | latest | Export a specific dataset version | | `--all` | bool | false | Unlimited bulk export (use for datasets > 500 examples) | | `--output-dir` | string | `.` | Output directory | | `--stdout` | bool | false | Print JSON to stdout instead of file | | `-p, --profile` | string | default | Configuration profile |

**Agent auto-escalation rule:** If an export returns exactly 500 examples, the result is likely truncated — re-run with `--all` to get the full dataset.

**Export completeness verification:** After exporting, confirm the row count matches what the server reports:

# Get the server-reported count from dataset metadata
ax datasets get DATASET_NAME --space SPACE -o json | jq '.versions[-1] | {version: .id, examples: .example_count}'

# Compare to what was exported
jq 'length' dataset_*/examples.json

# If counts differ, re-export with --all

Output is a JSON array of example objects. Each example has system fields (`id`, `created_at`, `updated_at`) plus all user-defined fields:

[
  {
    "id": "ex_001",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z",
    "question": "Wha