Datasets Client¶

The Datasets client provides methods for managing datasets in the Opik platform.

class opik.rest_api.datasets.client.DatasetsClient(*, client_wrapper: SyncClientWrapper)¶

Bases: object

apply_dataset_item_changes(id: str, *, request: Dict[str, Any | None], override: bool | None = None, request_options: RequestOptions | None = None) → DatasetVersionPublic¶

Apply delta changes (add, edit, delete) to a dataset version with conflict detection.

This endpoint: - Creates a new version with the applied changes - Validates that baseVersion matches the latest version (unless override=true) - Returns 409 Conflict if baseVersion is stale and override is not set

Use override=true query parameter to force version creation even with stale baseVersion.

Set ‘copy_from_dataset_id’ and ‘copy_from_version_id’ together on the request body to read carry-forward rows from the supplied (dataset, version) pair instead of the destination’s prior version. When the fields are null, carry-forward rows are read from the destination’s prior version.

Parameters:

id (str)
request (DatasetItemChangesPublic)
override (Optional[bool])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Version created successfully

Return type:

DatasetVersionPublic

batch_update_dataset_items(*, update: DatasetItemUpdate, ids: Sequence[str] | None = OMIT, filters: Sequence[DatasetItemFilter] | None = OMIT, dataset_id: str | None = OMIT, merge_tags: bool | None = OMIT, request_options: RequestOptions | None = None) → None¶

Update multiple dataset items

Parameters:

update (DatasetItemUpdate)
ids (Optional[Sequence[str]]) – List of dataset item IDs to update (max 1000). Mutually exclusive with ‘filters’.
filters (Optional[Sequence[DatasetItemFilter]])
dataset_id (Optional[str]) – Dataset ID. Required when using ‘filters’, optional when using ‘ids’.
merge_tags (Optional[bool]) – If true, merge tags with existing tags instead of replacing them. Default: false. When using ‘filters’, this is automatically set to true.
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Find datasets

Parameters:

page (Optional[int])
size (Optional[int])
with_experiments_only (Optional[bool])
with_optimizations_only (Optional[bool])
prompt_id (Optional[str])
project_id (Optional[str])
name (Optional[str])
sorting (Optional[str])
filters (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset resource

Return type:

DatasetPagePublic

Create dataset

Parameters:

name (str)
id (Optional[str])
project_id (Optional[str]) – Project ID. Takes precedence over project_name when both are provided.
project_name (Optional[str]) – For project scope, specify either project_id or project_name. If project_name is provided and the project does not exist, it will be created. Ignored when project_id is provided. If neither is provided, the dataset is created at workspace level.
type (Optional[DatasetWriteType])
visibility (Optional[DatasetWriteVisibility])
tags (Optional[Sequence[str]])
description (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Create/update dataset items based on dataset item id. Each item’s ‘id’ field is the stable identifier and upsert key. Provide it to update an existing item, or omit it to create a new one.

Set ‘copy_from_dataset_id’ and ‘copy_from_version_id’ together to read carry-forward rows from the supplied (dataset, version) pair instead of the destination’s prior version. When the fields are null, carry-forward rows are read from the destination’s prior version.

Parameters:

items (Sequence[DatasetItemWrite])
dataset_name (Optional[str]) – If null, dataset_id must be provided
dataset_id (Optional[str]) – If null, dataset_name must be provided
project_name (Optional[str]) – Optional. Associates the batch with a project by name. Ignored if project_id is provided.
project_id (Optional[str]) – Optional. Associates the batch with a project by ID. Takes precedence over project_name.
batch_group_id (Optional[str]) – Optional batch group ID to group multiple batches into a single dataset version. If null, mutates the latest version instead of creating a new one.
copy_from_dataset_id (Optional[str]) – Optional. Dataset to read carry-forward rows from when materializing the new version. Required together with copy_from_version_id. When null, carry-forward rows are read from the destination dataset’s prior version.
copy_from_version_id (Optional[str]) – Optional. Version within copy_from_dataset_id to read carry-forward rows from. Required together with copy_from_dataset_id.
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

create_dataset_items_from_csv(*, file: Dict[str, Any | None], dataset_id: str, request_options: RequestOptions | None = None) → None¶

Create dataset items from uploaded CSV file. CSV should have headers in the first row. Processing happens asynchronously in batches.

Parameters:

file (Dict[str, Optional[Any]])
dataset_id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

create_dataset_items_from_json(*, file: Dict[str, Any | None], dataset_id: str, format: Literal['json', 'jsonl'] | Any, request_options: RequestOptions | None = None) → None¶

Create dataset items from an uploaded JSON or JSONL file. JSON files must contain a top-level array of objects. JSONL files contain one JSON object per non-blank line; multi-line JSON objects are not supported. Reserved keys (id, source, description, tags, evaluators, execution_policy) are extracted into the corresponding DatasetItem fields; all remaining keys form the item’s data map and preserve their JSON types. To link dataset items to specific traces or spans use the dedicated /items/from-traces or /items/from-spans endpoints. Processing happens asynchronously in batches. With dataset versioning enabled, a supplied id acts as an upsert key.

Parameters:

file (Dict[str, Optional[Any]])
dataset_id (str)
format (CreateDatasetItemsFromJsonRequestFormat)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

create_dataset_items_from_spans(dataset_id: str, *, span_ids: Sequence[str], enrichment_options: SpanEnrichmentOptions, evaluators: Sequence[EvaluatorItem] | None = OMIT, execution_policy: ExecutionPolicy | None = OMIT, request_options: RequestOptions | None = None) → None¶

Create dataset items from spans with enriched metadata

Parameters:

dataset_id (str)
span_ids (Sequence[str]) – Set of span IDs to add to the dataset
enrichment_options (SpanEnrichmentOptions)
evaluators (Optional[Sequence[EvaluatorItem]]) – Optional evaluators to apply to the created items
execution_policy (Optional[ExecutionPolicy])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

create_dataset_items_from_traces(dataset_id: str, *, trace_ids: Sequence[str], enrichment_options: TraceEnrichmentOptions, evaluators: Sequence[EvaluatorItem] | None = OMIT, execution_policy: ExecutionPolicy | None = OMIT, request_options: RequestOptions | None = None) → None¶

Create dataset items from traces with enriched metadata

Parameters:

dataset_id (str)
trace_ids (Sequence[str]) – Set of trace IDs to add to the dataset
enrichment_options (TraceEnrichmentOptions)
evaluators (Optional[Sequence[EvaluatorItem]]) – Optional evaluators to apply to the created items
execution_policy (Optional[ExecutionPolicy])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

get_dataset_by_id(id: str, *, request_options: RequestOptions | None = None) → DatasetPublic¶

Get dataset by id

Parameters:

id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset resource

Return type:

DatasetPublic

Update dataset by id

Parameters:

id (str)
name (str)
description (Optional[str])
visibility (Optional[DatasetUpdateVisibility])
tags (Optional[Sequence[str]])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

delete_dataset(id: str, *, request_options: RequestOptions | None = None) → None¶

Delete dataset by id

Parameters:

id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

delete_dataset_by_name(*, dataset_name: str, project_name: str | None = OMIT, request_options: RequestOptions | None = None) → None¶

Delete dataset by name

Parameters:

dataset_name (str)
project_name (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Delete dataset items using one of two modes: 1. Delete by IDs: Provide ‘item_ids’ to delete specific items by their IDs 2. Delete by filters: Provide ‘dataset_id’ with optional ‘filters’ to delete items matching criteria

When using filters, an empty ‘filters’ array will delete all items in the specified dataset.

Parameters:

item_ids (Optional[Sequence[str]]) – List of dataset item IDs to delete (max 1000). Use this to delete specific items by their IDs. Mutually exclusive with ‘dataset_id’ and ‘filters’.
dataset_id (Optional[str]) – Dataset ID to scope the deletion. Required when using ‘filters’. Mutually exclusive with ‘item_ids’.
filters (Optional[Sequence[DatasetItemFilter]]) – Filters to select dataset items to delete within the specified dataset. Must be used with ‘dataset_id’. Mutually exclusive with ‘item_ids’. Empty array means ‘delete all items in the dataset’.
batch_group_id (Optional[str]) – Optional batch group ID to group multiple delete operations into a single dataset version. If null, mutates the latest version instead of creating a new one.
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

delete_datasets_batch(*, ids: Sequence[str], request_options: RequestOptions | None = None) → None¶

Delete datasets batch

Parameters:

ids (Sequence[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

download_dataset_export(job_id: str, *, request_options: RequestOptions | None = None) → Iterator[bytes]¶

Downloads the exported CSV file for a completed export job. This endpoint proxies the file download to avoid exposing internal storage URLs.

Parameters:

job_id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration. You can pass in configuration such as chunk_size, and more to customize the request and response.

Returns:

CSV file content

Return type:

Iterator[bytes]

expand_dataset(id: str, *, model: str, sample_count: int | None = OMIT, preserve_fields: Sequence[str] | None = OMIT, variation_instructions: str | None = OMIT, custom_prompt: str | None = OMIT, max_completion_tokens: int | None = OMIT, request_options: RequestOptions | None = None) → DatasetExpansionResponse¶

Generate synthetic dataset samples using LLM based on existing data patterns

Parameters:

id (str)
model (str) – The model to use for synthetic data generation
sample_count (Optional[int]) – Number of synthetic samples to generate
preserve_fields (Optional[Sequence[str]]) – Fields to preserve patterns from original data
variation_instructions (Optional[str]) – Additional instructions for data variation
custom_prompt (Optional[str]) – Custom prompt to use for generation instead of auto-generated one
max_completion_tokens (Optional[int]) – Maximum number of tokens for the LLM response. Required by Anthropic, used as maxOutputTokens for Gemini. If not provided, defaults to 4000 for Anthropic models only.
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Generated synthetic samples

Return type:

DatasetExpansionResponse

Find dataset items with experiment items

Parameters:

id (str)
experiment_ids (str)
page (Optional[int])
size (Optional[int])
filters (Optional[str])
sorting (Optional[str])
search (Optional[str])
truncate (Optional[bool])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset item resource

Return type:

DatasetItemPageCompare

get_dataset_by_identifier(*, dataset_name: str, project_name: str | None = OMIT, request_options: RequestOptions | None = None) → DatasetPublic¶

Get dataset by name

Parameters:

dataset_name (str)
project_name (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset resource

Return type:

DatasetPublic

get_dataset_experiment_items_stats(id: str, *, experiment_ids: str, filters: str | None = None, request_options: RequestOptions | None = None) → ProjectStatsPublic¶

Get experiment items stats for dataset

Parameters:

id (str)
experiment_ids (str)
filters (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Experiment items stats resource

Return type:

ProjectStatsPublic

get_dataset_export_job(job_id: str, *, request_options: RequestOptions | None = None) → DatasetExportJobPublic¶

Retrieves the current status of a dataset export job

Parameters:

job_id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Export job details

Return type:

DatasetExportJobPublic

get_dataset_export_jobs(*, request_options: RequestOptions | None = None) → List[DatasetExportJobPublic]¶

Retrieves all export jobs for the workspace. This is used to restore the export panel state after page refresh.

Parameters:: request_options (Optional[RequestOptions]) – Request-specific configuration.
Returns:: List of export jobs
Return type:: List[DatasetExportJobPublic]

get_dataset_item_by_id(item_id: str, *, request_options: RequestOptions | None = None) → DatasetItemPublic¶

Get dataset item by id

Parameters:

item_id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset item resource

Return type:

DatasetItemPublic

Partially update dataset item by id. Only provided fields will be updated.

Parameters:

item_id (str)
source (DatasetItemWriteSource)
data (JsonNode)
id (Optional[str]) – Stable item identifier. On write, used as the upsert key. If omitted, a new ID is generated. Remains the same across dataset versions
trace_id (Optional[str])
span_id (Optional[str])
description (Optional[str])
tags (Optional[Sequence[str]])
evaluators (Optional[Sequence[EvaluatorItemWrite]])
execution_policy (Optional[ExecutionPolicyWrite])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

Get dataset items

Parameters:

id (str)
page (Optional[int])
size (Optional[int])
version (Optional[str])
filters (Optional[str])
truncate (Optional[bool])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset items resource

Return type:

DatasetItemPagePublic

get_dataset_items_output_columns(id: str, *, experiment_ids: str | None = None, request_options: RequestOptions | None = None) → PageColumns¶

Get dataset items output columns

Parameters:

id (str)
experiment_ids (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset item output columns

Return type:

PageColumns

mark_dataset_export_job_viewed(job_id: str, *, request_options: RequestOptions | None = None) → None¶

Marks a dataset export job as viewed by setting the viewed_at timestamp. This is used to track that a user has seen a failed job’s error message. This operation is idempotent.

Parameters:

job_id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

start_dataset_export(id: str, *, request_options: RequestOptions | None = None) → DatasetExportJobPublic¶

Initiates an asynchronous CSV export job for the dataset. Returns immediately with job details for polling.

Parameters:

id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Existing export job in progress

Return type:

DatasetExportJobPublic

Stream dataset items

Parameters:

dataset_name (str)
last_retrieved_id (Optional[str])
steam_limit (Optional[int])
dataset_version (Optional[str])
project_name (Optional[str])
filters (Optional[str])
request_options (Optional[RequestOptions]) – Request-specific configuration. You can pass in configuration such as chunk_size, and more to customize the request and response.

Returns:

Dataset items stream or error during process

Return type:

Iterator[bytes]

compare_dataset_versions(id: str, *, request_options: RequestOptions | None = None) → DatasetVersionDiff¶

Compare the latest committed dataset version with the current draft state. This endpoint provides insights into changes made since the last version was committed. The comparison calculates additions, modifications, deletions, and unchanged items between the latest version snapshot and current draft.

Parameters:

id (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Diff computed successfully

Return type:

DatasetVersionDiff

create_version_tag(id: str, version_hash: str, *, tag: str, request_options: RequestOptions | None = None) → None¶

Add a tag to a specific dataset version for easy reference (e.g., ‘baseline’, ‘v1.0’, ‘production’)

Parameters:

id (str)
version_hash (str)
tag (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

delete_version_tag(id: str, version_hash: str, tag: str, *, request_options: RequestOptions | None = None) → None¶

Remove a tag from a dataset version. The version itself is not deleted, only the tag reference.

Parameters:

id (str)
version_hash (str)
tag (str)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Return type:

None

list_dataset_versions(id: str, *, page: int | None = None, size: int | None = None, request_options: RequestOptions | None = None) → DatasetVersionPagePublic¶

Get paginated list of versions for a dataset, ordered by creation time (newest first)

Parameters:

id (str)
page (Optional[int])
size (Optional[int])
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset versions

Return type:

DatasetVersionPagePublic

restore_dataset_version(id: str, *, version_ref: str, request_options: RequestOptions | None = None) → DatasetVersionPublic¶

Restores the dataset to a previous version state by creating a new version with items copied from the specified version. If the version is already the latest, returns it as-is (no-op).

Parameters:

id (str)
version_ref (str) – Version hash or tag to restore from
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Version restored successfully

Return type:

DatasetVersionPublic

retrieve_dataset_version(id: str, *, version_name: str, request_options: RequestOptions | None = None) → DatasetVersionPublic¶

Get a specific version by its version name (e.g., ‘v1’, ‘v373’). This is more efficient than paginating through all versions for large datasets.

Parameters:

id (str)
version_name (str) – Version name in format ‘vN’ (e.g., ‘v1’, ‘v373’)
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Dataset version

Return type:

DatasetVersionPublic

update_dataset_version(id: str, version_hash: str, *, change_description: str | None = OMIT, tags_to_add: Sequence[str] | None = OMIT, request_options: RequestOptions | None = None) → DatasetVersionPublic¶

Update a dataset version’s change_description and/or add new tags

Parameters:

id (str)
version_hash (str)
change_description (Optional[str]) – Optional description of changes in this version
tags_to_add (Optional[Sequence[str]]) – Optional list of tags to add to this version
request_options (Optional[RequestOptions]) – Request-specific configuration.

Returns:

Version updated successfully

Return type:

DatasetVersionPublic

Usage Example¶

import opik

client = opik.Opik()

# Find datasets
datasets = client.rest_client.datasets.find_datasets(
    page=0,
    size=10
)

# Get a dataset by ID
dataset = client.rest_client.datasets.get_dataset_by_id("dataset-id")

# Create a new dataset
client.rest_client.datasets.create_dataset(
    name="my-dataset",
    description="A test dataset"
)

# Get dataset items
items = client.rest_client.datasets.get_dataset_items(
    dataset_id="dataset-id",
    page=0,
    size=100
)