Datasets

The datasets client methods are currently in BETA. The API may change without notice. A one-time warning is emitted on first use.

A dataset is a versioned collection of examples used for experiments and evaluations. The Get, Update, Delete, ListExamples, AppendExamples, DeleteExamples, 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:

func (c *Client) List(ctx context.Context, req ListRequest) (*ListDatasets, error)

Usage Example:

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:

func (c *Client) Get(ctx context.Context, req GetRequest) (*Dataset, error)

Usage Example:

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:

func (c *Client) Create(ctx context.Context, req CreateRequest) (*Dataset, error)

Usage Example:

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.CreateDatasetExampleInput{
                {"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:

func (c *Client) Update(ctx context.Context, req UpdateRequest) (*Dataset, error)

Usage Example:

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:

func (c *Client) Delete(ctx context.Context, req DeleteRequest) error

Usage Example:

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:

func (c *Client) ListExamples(
    ctx context.Context,
    req ListExamplesRequest,
) (*ListDatasetExamples, error)

Usage Example:

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:

func (c *Client) AppendExamples(
    ctx context.Context,
    req AppendExamplesRequest,
) (*InsertDatasetExamples, error)

Usage Example:

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.CreateDatasetExampleInput{
                {"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,
    )
}

Update Examples

UpdateExamples updates existing examples in a dataset version by example ID and returns the version they were written to along with the updated example IDs, resolving the dataset by name or ID. Each entry in Examples must include the example Id; arbitrary user-defined fields are supplied through AdditionalProperties. DatasetVersionID is optional — when empty, the server uses the dataset’s latest version. When NewVersion is set, the update is captured as a new dataset version; otherwise the selected version is updated in place. Signature:

func (c *Client) UpdateExamples(
    ctx context.Context,
    req UpdateDatasetExamplesRequest,
) (*UpdateDatasetExamplesResponse, error)

Usage Example:

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)
    }

    updated, err := client.Datasets.UpdateExamples(
        context.Background(),
        datasets.UpdateDatasetExamplesRequest{
            Dataset: "your-dataset-name-or-id",
            Space:   "your-space-name-or-id",
            Examples: []datasets.UpdateDatasetExampleInput{
                {
                    Id:                   "example-id-1",
                    AdditionalProperties: map[string]any{"expected": "updated answer"},
                },
            },
        },
    )
    if err != nil {
        var badRequest *arize.BadRequestError
        if errors.As(err, &badRequest) {
            log.Fatalf("invalid examples: %v", badRequest)
        }
        log.Fatal(err)
    }

    fmt.Printf("updated %d examples in version %s\n",
        len(updated.ExampleIds),
        updated.DatasetVersionId,
    )
}

Delete Examples

DeleteExamples removes a batch of examples from a specific dataset version, resolving the dataset by name or ID. DatasetVersionID is required — deletions are always scoped to a specific version. The response reports which IDs were deleted (DeletedExampleIds) and which were not (NotDeletedExampleIds); when Completed is false the delete did not fully complete and the full request should be retried, which is safe because the operation is idempotent. Signature:

func (c *Client) DeleteExamples(
    ctx context.Context,
    req DeleteExamplesRequest,
) (*DeleteDatasetExamples, error)

Usage Example:

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)
    }

    result, err := client.Datasets.DeleteExamples(
        context.Background(),
        datasets.DeleteExamplesRequest{
            Dataset:          "your-dataset-name-or-id",
            Space:            "your-space-name-or-id",
            DatasetVersionID: "your-dataset-version-id",
            ExampleIDs:       []string{"example-id-1", "example-id-2"},
        },
    )
    if err != nil {
        var notFound *arize.NotFoundError
        if errors.As(err, &notFound) {
            log.Fatalf("dataset not found: %v", notFound)
        }
        log.Fatal(err)
    }

    if !result.Completed {
        fmt.Printf("partial delete: confirmed %d example IDs - retry the original request to resolve %d remaining\n",
            len(result.DeletedExampleIds),
            len(result.NotDeletedExampleIds),
        )
        return
    }
    fmt.Printf("deleted %d examples (%d not found)\n",
        len(result.DeletedExampleIds),
        len(result.NotDeletedExampleIds),
    )
}

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:

func (c *Client) AnnotateExamples(ctx context.Context, req AnnotateExamplesRequest) error

Usage Example:

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)
    }
}

API reference

API clients

List Datasets

Get a Dataset

Create a Dataset

Update a Dataset

Delete a Dataset

List Examples

Append Examples

Update Examples

Delete Examples

Annotate Examples

​List Datasets

​Get a Dataset

​Create a Dataset

​Update a Dataset

​Delete a Dataset

​List Examples

​Append Examples

​Update Examples

​Delete Examples

​Annotate Examples

List Datasets

Get a Dataset

Create a Dataset

Update a Dataset

Delete a Dataset

List Examples

Append Examples

Update Examples

Delete Examples

Annotate Examples