Dataset

class opik.Dataset(name: str, description: str | None, project_name: str | None, rest_client: OpikApi, dataset_items_count: int | None = None, client: Any | None = None)

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) → 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: Sequence[Dict[str, Any]]) → None

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

Parameters:

items – List of dicts (which will be converted to dataset items) to add to the dataset.

update(items: List[Dict[str, Any]]) → None

Update existing items in the dataset.

Parameters:

items – List of DatasetItem objects to update in the dataset. You need to provide the full item object as it will override what has been supplied previously.

Raises:

DatasetItemUpdateOperationRequiresItemId – If any item in the list is missing an id.

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.

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

read_jsonl_from_file(file_path: str, keys_mapping: Dict[str, str] | None = None, ignore_keys: List[str] | None = None) → None

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

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

insert_from_pandas(dataframe: pd.DataFrame, keys_mapping: Dict[str, str] | None = None, ignore_keys: List[str] | None = None) → 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

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