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

> List, get, create, update, delete, and manage examples and annotations for datasets using the Arize Go SDK.

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

A dataset is a versioned collection of examples used for experiments and evaluations. The `Get`, `Update`, `Delete`, `ListExamples`, `AppendExamples`, and `AnnotateExamples` methods accept either a dataset name or an ID — when a name is passed, the parent `Space` (name or ID) is also required so the SDK can resolve the name to a unique ID. Datasets cannot be empty: `Create` requires at least one example, otherwise it returns `datasets.ErrNoExamples`.

## List Datasets

`List` returns a paginated list of datasets. `Space`, when non-empty, restricts results to a single space.

**Signature:**

```go theme={null}
func (c *Client) List(ctx context.Context, req ListRequest) (*DatasetList, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/datasets"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Datasets.List(context.Background(), datasets.ListRequest{
        Space: "your-space-name-or-id",
        Limit: 25,
    })
    if err != nil {
        var unauthorized *arize.UnauthorizedError
        if errors.As(err, &unauthorized) {
            log.Fatalf("unauthorized: %v", unauthorized)
        }
        log.Fatal(err)
    }

    for _, ds := range resp.Datasets {
        fmt.Printf("%s: %s\n", ds.Id, ds.Name)
    }
}
```

## Get a Dataset

`Get` returns a single dataset, resolving by name or ID. `Space` is required when `Dataset` is a name.

**Signature:**

```go theme={null}
func (c *Client) Get(ctx context.Context, req GetRequest) (*Dataset, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/datasets"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ds, err := client.Datasets.Get(
        context.Background(),
        datasets.GetRequest{
            Dataset: "your-dataset-name-or-id",
            Space:   "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("dataset not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("dataset %s: %s\n", ds.Id, ds.Name)
}
```

## Create a Dataset

`Create` creates a new dataset in the given space and returns it. The parent space is resolved by name or ID. At least one example is required; an empty `Examples` slice returns `datasets.ErrNoExamples` without contacting the server.

**Signature:**

```go theme={null}
func (c *Client) Create(ctx context.Context, req CreateRequest) (*Dataset, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/datasets"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ds, err := client.Datasets.Create(
        context.Background(),
        datasets.CreateRequest{
            Space: "your-space-name-or-id",
            Name:  "your-new-dataset",
            Examples: []datasets.DatasetExampleCreate{
                {"input": "hello", "expected": "hi"},
            },
        },
    )
    if err != nil {
        if errors.Is(err, datasets.ErrNoExamples) {
            log.Fatal("cannot create dataset without examples")
        }
        var conflict *arize.ConflictError
        if errors.As(err, &conflict) {
            log.Fatalf("dataset already exists: %v", conflict)
        }
        log.Fatal(err)
    }

    fmt.Printf("created dataset %s\n", ds.Id)
}
```

## Update a Dataset

`Update` renames a dataset, resolving by name or ID, and returns the updated dataset. `Space` is required when `Dataset` is a name.

**Signature:**

```go theme={null}
func (c *Client) Update(ctx context.Context, req UpdateRequest) (*Dataset, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/datasets"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    ds, err := client.Datasets.Update(
        context.Background(),
        datasets.UpdateRequest{
            Dataset: "your-dataset-name-or-id",
            Space:   "your-space-name-or-id",
            Name:    "renamed-dataset",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("dataset not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("updated dataset %s: %s\n", ds.Id, ds.Name)
}
```

## Delete a Dataset

`Delete` irreversibly removes a dataset, resolving by name or ID. It returns only an error.

**Signature:**

```go theme={null}
func (c *Client) Delete(ctx context.Context, req DeleteRequest) error
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/datasets"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    err = client.Datasets.Delete(
        context.Background(),
        datasets.DeleteRequest{
            Dataset: "your-dataset-name-or-id",
            Space:   "your-space-name-or-id",
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Printf("no dataset to remove: %v", notFound)
            return
        }
        log.Fatal(err)
    }
}
```

## List Examples

`ListExamples` returns a paginated list of examples for a dataset, resolving the dataset by name or ID. `DatasetVersionID` is optional — when empty, the server uses the dataset's latest version.

**Signature:**

```go theme={null}
func (c *Client) ListExamples(
    ctx context.Context,
    req ListExamplesRequest,
) (*DatasetExampleList, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/datasets"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    resp, err := client.Datasets.ListExamples(
        context.Background(),
        datasets.ListExamplesRequest{
            Dataset: "your-dataset-name-or-id",
            Space:   "your-space-name-or-id",
            Limit:   50,
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("dataset not found: %v", notFound)
        }
        log.Fatal(err)
    }

    fmt.Printf("loaded %d examples\n", len(resp.Examples))
}
```

## Append Examples

`AppendExamples` appends new examples to a dataset version and returns the version they were written to along with the server-assigned example IDs. `DatasetVersionID` is optional — when empty, the server uses the dataset's latest version.

**Signature:**

```go theme={null}
func (c *Client) AppendExamples(
    ctx context.Context,
    req AppendExamplesRequest,
) (*DatasetExamplesInserted, error)
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/datasets"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    inserted, err := client.Datasets.AppendExamples(
        context.Background(),
        datasets.AppendExamplesRequest{
            Dataset: "your-dataset-name-or-id",
            Space:   "your-space-name-or-id",
            Examples: []datasets.DatasetExampleCreate{
                {"input": "good morning", "expected": "good morning to you"},
            },
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("invalid examples: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("appended %d examples to version %s\n",
        len(inserted.ExampleIds),
        inserted.DatasetVersionId,
    )
}
```

## Annotate Examples

`AnnotateExamples` writes human annotations to a batch of examples in a dataset. Annotations are upserted by annotation config name for each example, so re-annotating the same example with the same config name overwrites the previous value. Up to 1000 examples may be annotated per request.

**Signature:**

```go theme={null}
func (c *Client) AnnotateExamples(ctx context.Context, req AnnotateExamplesRequest) error
```

**Usage Example:**

```go theme={null}
package main

import (
    "context"
    "errors"
    "log"

    "github.com/Arize-ai/client-go-v2/arize"
    "github.com/Arize-ai/client-go-v2/arize/datasets"
)

func main() {
    client, err := arize.NewClient(arize.Config{APIKey: "your-api-key"})
    if err != nil {
        log.Fatal(err)
    }

    label := "correct"
    err = client.Datasets.AnnotateExamples(
        context.Background(),
        datasets.AnnotateExamplesRequest{
            Dataset: "your-dataset-name-or-id",
            Space:   "your-space-name-or-id",
            Annotations: []datasets.AnnotateRecordInput{
                {
                    RecordId: "example-id-1",
                    Values: []datasets.AnnotationInput{
                        {Name: "quality", Label: &label},
                    },
                },
            },
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("annotation rejected: %v", badRequest)
        }
        log.Fatal(err)
    }
}
```