Datasets

The Opik TypeScript SDK provides robust functionality for creating and managing datasets. Datasets in Opik serve as collections of data items that can be used for various purposes, including evaluation.

Dataset Fundamentals

A dataset in Opik is a named collection of data items. Each dataset:

• Has a unique identifier and name
• Contains items that share a common structure
• Supports powerful deduplication capabilities
• Using for evaluation

TypeScript Type Safety

One of the key features of the Opik SDK is strong TypeScript typing support for datasets. You can define custom types for your dataset items to ensure type safety throughout your application:

1
// Define a custom dataset item type
2
type QuestionAnswerItem = {
3
  question: string;
4
  answer: string;
5
  metadata: {
6
    category: string;
7
    difficulty: string;
8
  };
9
};
10
11
// Create a typed dataset
12
const dataset = await opik.createDataset<QuestionAnswerItem>(
13
  "qa-dataset", // Dataset name
14
  "Question-Answer pairs for evaluation" // Dataset description
15
);

Working with Datasets

Creating Datasets

1
// Create a new dataset
2
await opik.createDataset<YourItemType>(
3
  "dataset-name",
4
  "Optional dataset description"
5
);
6
7
// Get an existing dataset or create it if it doesn't exist
8
const dataset = await opik.getOrCreateDataset<YourItemType>(
9
  "dataset-name",
10
  "Optional dataset description"
11
);

Managing Dataset Items

1
// Insert items
2
await dataset.insert([
3
  { id: "item1", question: "What is ML?", answer: "Machine learning is..." },
4
  {
5
    id: "item2",
6
    question: "What is AI?",
7
    answer: "Artificial intelligence is...",
8
  },
9
]);
10
11
// Update existing items
12
await dataset.update([
13
  {
14
    id: "item1",
15
    question: "What is Machine Learning?",
16
    answer: "Updated answer...",
17
  },
18
]);
19
20
// Delete specific items
21
await dataset.delete(["item1", "item2"]);
22
23
// Clear all items from the dataset
24
await dataset.clear();

Retrieving Dataset Items

1
// Get a specific number of items
2
const items = await dataset.getItems(10);
3
4
// Get items with pagination
5
const firstBatch = await dataset.getItems(10);
6
const lastItemId = firstBatch[firstBatch.length - 1].id;
7
const nextBatch = await dataset.getItems(10, lastItemId);

Working with JSON

1
// Import items from a JSON string
2
const jsonData = JSON.stringify([
3
  {
4
    query: "What is the capital of France?",
5
    response: "Paris",
6
    tags: ["geography", "europe"],
7
  },
8
]);
9
10
// Map JSON keys to dataset item fields
11
const keysMapping = {
12
  query: "question", // 'query' in JSON becomes 'question' in dataset item
13
  response: "answer", // 'response' in JSON becomes 'answer' in dataset item
14
  tags: "metadata.tags", // 'tags' in JSON becomes 'metadata.tags' in dataset item
15
};
16
17
// Specify keys to ignore
18
const ignoreKeys = ["irrelevant_field"];
19
20
// Insert from JSON with mapping
21
await dataset.insertFromJson(jsonData, keysMapping, ignoreKeys);
22
23
// Export dataset to JSON with custom key mapping
24
const exportMapping = { question: "prompt", answer: "completion" };
25
const exportedJson = await dataset.toJson(exportMapping);

API Reference

OpikClient Dataset Methods

createDataset<T>

Creates a new dataset.

Arguments:

• name: string - The name of the dataset
• description?: string - Optional description of the dataset

Returns: Promise<Dataset<T>> - A promise that resolves to the created Dataset object

getDataset<T>

Retrieves an existing dataset by name.

Arguments:

• name: string - The name of the dataset to retrieve

Returns: Promise<Dataset<T>> - A promise that resolves to the Dataset object

getOrCreateDataset<T>

Retrieves an existing dataset by name or creates it if it doesn’t exist.

Arguments:

• name: string - The name of the dataset
• description?: string - Optional description (used only if creating a new dataset)

Returns: Promise<Dataset<T>> - A promise that resolves to the existing or newly created Dataset object

getDatasets<T>

Retrieves a list of datasets.

Arguments:

• maxResults?: number - Optional maximum number of datasets to retrieve (default: 100)

Returns: Promise<Dataset<T>[]> - A promise that resolves to an array of Dataset objects

deleteDataset

Deletes a dataset by name.

Arguments:

• name: string - The name of the dataset to delete

Returns: Promise<void>

Dataset Class Methods

insert

Inserts new items into the dataset with automatic deduplication.

Arguments:

• items: T[] - List of objects to add to the dataset

Returns: Promise<void>

update

Updates existing items in the dataset.

Arguments:

• items: T[] - List of objects to update in the dataset (must include IDs)

Returns: Promise<void>

delete

Deletes items from the dataset.

Arguments:

• itemIds: string[] - List of item IDs to delete

Returns: Promise<void>

clear

Deletes all items from the dataset.

Returns: Promise<void>

getItems

Retrieves items from the dataset.

Arguments:

• nbSamples?: number - Optional number of items to retrieve (if not set, all items are returned)
• lastRetrievedId?: string - Optional ID of the last retrieved item for pagination

Returns: Promise<T[]> - A promise that resolves to an array of dataset items

insertFromJson

Inserts items from a JSON string into the dataset.

Arguments:

• jsonArray: string - JSON string in array format
• keysMapping?: Record<string, string> - Optional dictionary that maps JSON keys to dataset item field names
• ignoreKeys?: string[] - Optional array of keys to ignore when constructing dataset items

Returns: Promise<void>

toJson

Exports the dataset to a JSON string.

Arguments:

• keysMapping?: Record<string, string> - Optional dictionary that maps dataset item field names to output JSON keys

Returns: Promise<string> - A JSON string representation of all items in the dataset