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

> 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 examples = await listDatasetExamples({
  dataset: "your_dataset_id",
  datasetVersionId: "your_dataset_version_id",  // optional
  limit: 10,
});
```

## 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",
    },
  ],
  newVersionName: "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" },
      ],
    },
  ],
});
```