Dataset¶

Bases: DatasetExportOperations

__init__(name: str, description: str | None, project_name: str | None, rest_client: OpikApi, dataset_items_count: int | None = None, client: Any | None = None, rest_httpx_client: Client | None = None, url_override: str | None = None) → None¶: A Dataset object. This object should not be created directly, instead use opik.Opik.create_dataset() or opik.Opik.get_dataset().

classmethod from_public(dataset_fern: DatasetPublic, project_name: str, rest_client: OpikApi, client: Any | None = None) → Dataset¶

Build a Dataset from a backend response, resolving the actual project.

The backend may find the dataset via workspace-wide fallback even when the caller’s project_name doesn’t match the dataset’s actual project. This method uses project_id from the response to resolve the real project name, so downstream calls target the correct project.

property id: str¶: The id of the dataset

property name: str¶: The name of the dataset.

property project_name: str | None¶: The name of the project this dataset belongs to.

property description: str | None¶: The description of the dataset.

property dataset_items_count: int | None¶

The total number of items in the dataset.

If the count is not cached locally, it will be fetched from the backend.

get_current_version_name() → str | None¶

Get the current version name of the dataset.

The version name is fetched from the backend and reflects the latest committed version after any mutation operations (insert, update, delete).

Returns:: The current version name (e.g., ‘v1’, ‘v2’), or None if no version exists.

get_version_info() → DatasetVersionPublic | None¶

Get version information for the current (latest) dataset version.

Returns:: DatasetVersionPublic containing the current version’s metadata, or None if no version exists yet.

get_evaluators(evaluator_model: str | None = None) → List[Any]¶

Get suite-level evaluators from the current dataset version.

Converts EvaluatorItemPublic objects from the BE into LLMJudge instances.

Parameters:: evaluator_model – Optional model name to use for LLMJudge evaluators.
Returns:: List of LLMJudge instances extracted from the version.

get_execution_policy() → ExecutionPolicy¶

Get suite-level execution policy from the current dataset version.

Returns:: ExecutionPolicy dict with runs_per_item and pass_threshold.

get_tags() → List[str]¶

Get the tags for this dataset.

Returns:: List of tag strings.

insert(items: Iterable[Dict[str, Any]], num_threads: int = constants.DATASET_ITEMS_WRITE_NUM_THREADS, deduplication: bool = True) → None¶

Insert new items into the dataset. A new dataset version will be created.

Parameters:

items – Dicts to add to the dataset. Any iterable is accepted, including a generator, and it is consumed lazily, so no item is retained once its request has been sent and the request bodies in flight are capped. That is the bounded part; deduplication is not, and keeps a content digest and an id per item for the life of the Dataset however the items arrived – pass deduplication=False for an upload that retains nothing at all. A list keeps working as before, and its items are checked for shape before the first request goes out; from a generator not even that is possible. Either way a value that cannot be serialised is found when the item carrying it is reached, and the items sent before it stay persisted – a single-pass upload cannot know the last item is invalid before sending the first batch.
deduplication – Whether to skip items whose content already exists in the dataset. Pass False to insert every item as-is without any duplicate checking, which is significantly faster on large datasets. The next insert that does deduplicate has to re-read the dataset’s items to account for what was skipped.
num_threads – Number of worker threads used to upload the item batches. Must be a positive integer, defaults to 8; pass 1 to upload sequentially, or a higher number to push a large upload harder, up to 32 – beyond that it is clamped rather than rejected, as on the read path. It also sizes how much the upload holds: request bodies are queued uncompressed, up to 2 * num_threads of them at MAX_BATCH_SIZE_MB each – about 80 MB at the default 8, and about 320 MB at 32. Raise it for throughput, lower it where memory is tight. All batches land in a single dataset version. If a batch fails the call raises, and the batches that already succeeded stay persisted; above 1 the bodies already queued are drained and awaited first, so they land too and the exception surfaces after them. Older Opik backends do not support parallel upload and fall back to a sequential one.

Raises:

ValueError – If num_threads is not a positive integer, if deduplication is not a bool, if an item in a list is neither a dict nor a DatasetItem, or if an item’s id, trace_id or span_id is not a UUID.

update(items: Iterable[Dict[str, Any]], deduplication: bool = True) → None¶

Update existing items in the dataset.

Parameters:

items – Dicts to update in the dataset. You need to provide the full item object as it will override what has been supplied previously. Any iterable is accepted, including a generator.
deduplication – Whether to skip items whose content already exists in the dataset. See insert() for details.

Raises:

DatasetItemUpdateOperationRequiresItemId – If an item is missing an id. The item’s position in the input is included in the message. A list is scanned before anything is sent; from a generator the missing id is found when its item is reached, and the items before it stay persisted.

delete(items_ids: List[str]) → None¶

Delete items from the dataset. A new dataset version will be created.

Parameters:: items_ids – List of item ids to delete. Ids are normalised the way insert() normalises them, so an item inserted with a uuid.UUID object can be deleted by that object or by its string form.
Raises:: ValueError – If an id is None or empty. The item’s position in the input is included in the message.

clear() → None¶: Delete all items from the given dataset. A new dataset version will be created.

insert_from_json(json_array: str, keys_mapping: Dict[str, str] | None = None, ignore_keys: List[str] | None = None, deduplication: bool = True) → None¶

Parameters:

json_array – json string of format: “[{…}, {…}, {…}]” where every dictionary is to be transformed into dataset item
keys_mapping – dictionary that maps json keys to item fields names Example: {‘Expected output’: ‘expected_output’}
ignore_keys – if your json dicts contain keys that are not needed for DatasetItem construction - pass them as ignore_keys argument
deduplication – Whether to skip items whose content already exists in the dataset. See insert() for details.

read_jsonl_from_file(file_path: str, keys_mapping: Dict[str, str] | None = None, ignore_keys: List[str] | None = None, deduplication: bool = True, validate_before_upload: bool = True) → None¶

Read JSONL from a file and insert it into the dataset.

The file is parsed one line at a time and uploaded as it is read, so a file larger than memory can be inserted whichever way validate_before_upload is set: neither the file nor the items it holds are retained. Deduplication is the exception and is unchanged – with deduplication=True a digest and an id per item are kept for the life of the Dataset, around 0.3 KB each.

The file is read from the start twice when validate_before_upload is on, so it has to be re-readable. A path that cannot be re-read – a pipe or a character device – is uploaded in a single pass instead, and a warning says so, rather than validating the stream and then finding nothing left to upload.

Parameters:

file_path – Path to the JSONL file
keys_mapping – dictionary that maps json keys to item fields names Example: {‘Expected output’: ‘expected_output’}
ignore_keys – if your json dicts contain keys that are not needed for DatasetItem construction - pass them as ignore_keys argument
deduplication – Whether to skip items whose content already exists in the dataset. See insert() for details.
validate_before_upload – Whether the file is checked before the upload starts, rather than as it goes. Every item is validated either way, so this decides when a bad one is reported, not whether it is. True (the default) reads the file once first, so a bad line raises before any request – the check insert() runs on a list and cannot run on a generator – at the cost of parsing the file twice and no extra memory. False uploads in a single pass and validates each item as it is sent, so a bad line raises when it is reached, with the items before it persisted and no rollback.

Raises:

ValueError – If an item’s id, trace_id or span_id is not a UUID. With validate_before_upload it names the item’s position among the items read – blank lines are skipped, so that is not a line number – and nothing has been sent; a malformed line, or a value pydantic rejects, is raised there too. A value that cannot be serialised is found when its item is reached either way, as it is for a list.

insert_from_pandas(dataframe: pd.DataFrame, keys_mapping: Dict[str, str] | None = None, ignore_keys: List[str] | None = None, deduplication: bool = True) → None¶

Requires: pandas library to be installed.

Parameters:

dataframe – pandas dataframe
keys_mapping – Dictionary that maps dataframe column names to dataset item field names. Example: {‘Expected output’: ‘expected_output’}
ignore_keys – if your dataframe contains columns that are not needed for DatasetItem construction - pass them as ignore_keys argument
deduplication – Whether to skip items whose content already exists in the dataset. See insert() for details.

get_version_view(version_name: str) → DatasetVersion¶

Get a read-only view of a specific dataset version.

The returned DatasetVersion object allows reading version metadata and retrieving items via DatasetVersion.get_items(), but does not support mutations.

Parameters:: version_name – The version name (e.g., ‘v1’, ‘v2’).
Returns:: A read-only DatasetVersion object for accessing the specified version.
Raises:: opik.exceptions.DatasetVersionNotFound – If the specified version does not exist.

Example

>>> dataset = client.get_dataset("my_dataset")
>>> version = dataset.get_version_view("v1")
>>> items = version.get_items()