> ## 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

> Create versioned datasets for experimentation, evaluation, and fine-tuning using the Arize TypeScript SDK.

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

## List Datasets

```typescript theme={null}
import { listDatasets } from "@arizeai/ax-client";

const { data: datasets, pagination } = await listDatasets({
  space: "my-space",   // space name or ID (optional)
  name: "qa",          // substring filter on dataset name (optional)
  limit: 10,
});
```

## Create a Dataset

```typescript theme={null}
import { createDataset } from "@arizeai/ax-client";

const dataset = await createDataset({
  space: "my-space",  // space name or ID
  name: "your_dataset_name",
  examples: [{ question: "What is 2+2?", answer: "4", topic: "math" }],
});
```

## Get a Dataset

```typescript theme={null}
import { getDataset } from "@arizeai/ax-client";

// By ID
const dataset = await getDataset({ dataset: "your_dataset_id" });

// By name (requires space)
const dataset = await getDataset({ dataset: "my-dataset", space: "my-space" });
```

## Update a Dataset

Rename a dataset. The new `name` must be unique within the space.

```typescript theme={null}
import { updateDataset } from "@arizeai/ax-client";

const dataset = await updateDataset({
  dataset: "my-dataset",  // dataset name or ID
  space: "my-space",      // required when dataset is a name
  name: "my-renamed-dataset",
});
```

## Delete a Dataset

```typescript theme={null}
import { deleteDataset } from "@arizeai/ax-client";

// By ID
await deleteDataset({ dataset: "your_dataset_id" });

// By name (requires space)
await deleteDataset({ dataset: "my-dataset", space: "my-space" });
```

## List Dataset Examples

```typescript theme={null}
import { listDatasetExamples } from "@arizeai/ax-client";

const { data: examples, pagination } = await listDatasetExamples({
  dataset: "my-dataset",                       // dataset name or ID
  space: "my-space",                           // required when dataset is a name
  datasetVersionId: "your_dataset_version_id", // optional, defaults to latest
  limit: 10,
});
console.log(examples);
if (pagination.hasMore) {
  const nextPage = await listDatasetExamples({
    dataset: "my-dataset",
    space: "my-space",
    cursor: pagination.nextCursor,
  });
}
```

## Append Examples

```typescript theme={null}
import { appendExamples } from "@arizeai/ax-client";

const result = await appendExamples({
  dataset: "my-dataset",  // dataset name or ID
  space: "my-space",      // required when dataset is a name
  examples: [
    { question: "What is 3+3?", answer: "6", topic: "math" },
  ],
});
console.log(result.exampleIds); // IDs of the inserted examples
```

## Update Dataset Examples

```typescript theme={null}
import { updateExamples } from "@arizeai/ax-client";

const result = await updateExamples({
  dataset: "my-dataset",  // dataset name or ID
  space: "my-space",      // required when dataset is a name
  examples: [
    {
      id: "your_example_id",
      question: "What is 2+2?",
      answer: "4",
      topic: "math",
    },
  ],
  newVersion: "v2",  // optional: create a new version instead of updating in place
});
console.log(result.exampleIds); // IDs of the updated examples
```

## Annotate Dataset Examples

Write human annotations to a batch of examples in a dataset. Annotations are upserted by annotation config name for each example; submitting the same name for the same example overwrites the previous value. Up to 1000 examples may be annotated per request.

```typescript theme={null}
import { annotateDatasetExamples } from "@arizeai/ax-client";

await annotateDatasetExamples({
  dataset: "my-dataset",  // dataset name or ID
  space: "my-space",      // required when dataset is a name
  annotations: [
    {
      recordId: "your_example_id",
      values: [
        { name: "quality", score: 0.9 },
        { name: "topic", label: "science" },
      ],
    },
  ],
});
```

## Delete Dataset Examples

Delete a batch of examples from a dataset version by their IDs. Examples are removed in place from the given version; no new version is created. The request is partial-tolerant and idempotent — re-submitting already-deleted IDs is safe. Between 1 and 1000 IDs per request.

```typescript theme={null}
import { deleteDatasetExamples } from "@arizeai/ax-client";

const result = await deleteDatasetExamples({
  dataset: "my-dataset",  // dataset name or ID
  space: "my-space",      // required when dataset is a name
  datasetVersionId: "your_dataset_version_id",
  examples: ["your_example_id_1", "your_example_id_2"],
});
if (!result.completed) {
  // retry the original full request — the delete is idempotent
}
console.log(result.deletedExampleIds, result.notDeletedExampleIds);
```