[OPIK-4149] [SDK] Add DatasetVersion support to TypeScript SDK #5068

awkoy · 2026-02-04T16:36:32Z

Details

Add dataset versioning capabilities allowing users to work with specific snapshots of datasets. This enables reproducible evaluations by pinning to a specific version.

Changes:

Add DatasetVersion class for read-only version views
Add Dataset.getVersionView(), getCurrentVersionName(), getVersionInfo()
Support DatasetVersion in evaluate() with version tracking
Add DatasetVersionNotFoundError for version lookup failures
Export Dataset, DatasetVersion, DatasetVersionNotFoundError from SDK
Add comprehensive unit tests (32 tests) and integration tests (3 tests)

The DatasetVersion class provides a read-only view of dataset items at a specific version. It exposes all version metadata (versionId, versionHash, tags, itemsTotal, etc.) and supports fetching items via getItems() and serialization via toJson().

Key implementation details:

DatasetVersion follows the same HTTP access pattern as Dataset and Experiment for read operations (direct API calls)
getVersionView() uses pagination to find versions by name
evaluate() now accepts DatasetVersion and links experiments to the specific version via datasetVersionId
DatasetVersionPublic type is exported from the SDK for public use

Change checklist

User facing
Documentation update

Issues

OPIK-4149

Documentation

Testing

32 unit tests covering DatasetVersion properties, getItems, toJson, and Dataset version methods
5 integration tests covering evaluate with DatasetVersion
All tests passing

github-actions · 2026-02-04T16:36:50Z

📋 PR Linter Failed

❌ Incomplete Details Section. The ## Details section cannot be empty.

sdks/typescript/src/opik/dataset/DatasetVersion.ts

sdks/typescript/tests/dataset/datasetVersion.test.ts

github-actions · 2026-02-05T09:55:06Z

📋 PR Linter Failed

❌ Incomplete Details Section. The ## Details section cannot be empty.

github-actions · 2026-02-05T10:57:21Z

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Documentation section.

github-actions · 2026-02-05T11:27:17Z

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Documentation section.

github-actions · 2026-02-05T11:28:41Z

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Documentation section.

Add dataset versioning capabilities allowing users to work with specific snapshots of datasets. This enables reproducible evaluations by pinning to a specific version. Changes: - Add DatasetVersion class for read-only version views - Add Dataset.getVersionView(), getCurrentVersionName(), getVersionInfo() - Support DatasetVersion in evaluate() with version tracking - Add DatasetVersionNotFoundError for version lookup failures - Export Dataset, DatasetVersion, DatasetVersionNotFoundError from SDK - Add comprehensive unit tests (32 tests) and integration tests (3 tests)

- Remove redundant if wrapper in toJson keysMapping loop - Export DatasetVersionPublic type from SDK public API - Update test imports to use public SDK exports Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Add "Working with Dataset Versions" section to datasets.mdx with examples for getVersionView, getCurrentVersionName, and getVersionInfo methods - Document DatasetVersion class properties and methods in API reference - Update evaluate.mdx to show Dataset | DatasetVersion parameter type - Add TypeScript version selection example to manage_datasets.mdx Co-Authored-By: Claude Opus 4.5 <[email protected]>

github-actions · 2026-02-05T11:54:36Z

🌿 Preview your docs: https://opik-preview-dde1d2c4-eb50-434c-9309-18ee795f28ed.docs.buildwithfern.com/docs/opik

No broken links found

📌 Results for commit 948046c

The backend's resolveVersionId method looks up versions by hash or tag, not by versionName. Changed to pass versionHash instead of versionName to match Python SDK behavior and fix E2E test failures. Co-Authored-By: Claude Opus 4.5 <[email protected]>

sdks/typescript/tests/dataset/datasetVersion.test.ts

sdks/typescript/tests/evaluation/evaluateWithVersion.test.ts

sdks/typescript/src/opik/dataset/DatasetVersion.ts

Add scoringKeyMapping to map 'expected' to 'expected_output' field in the dataset items, matching the pattern used in other evaluation tests. Co-Authored-By: Claude Opus 4.5 <[email protected]>

…on parity Adds the lastRetrievedId parameter to DatasetVersion.getItems() to match the Dataset.getItems() API. This allows manual pagination for datasets with more than 2000 items. Co-Authored-By: Claude Opus 4.5 <[email protected]>

This adds automatic pagination support for retrieving large datasets: - Dataset.getItemsAsDataclasses() now fetches all items automatically - DatasetVersion.getItemsAsDataclasses() uses the same pagination pattern - Both use cursor-based pagination with lastRetrievedId - Maximum batch size of 2000 items per request (API limit) - Pagination continues until all requested items are retrieved This provides parity with the Python SDK's auto-pagination behavior. Co-Authored-By: Claude Opus 4.5 <[email protected]>

sdks/typescript/src/opik/dataset/Dataset.ts

sdks/typescript/src/opik/dataset/DatasetVersion.ts

Return empty array immediately when nbSamples === 0 to avoid API call with invalid steamLimit = 0 (API requires steamLimit >= 1). Co-Authored-By: Claude Opus 4.5 <[email protected]>

sdks/typescript/src/opik/dataset/Dataset.ts

Simplify streamLimit calculation using nullish coalescing operator. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Add await to createExperiment API call to ensure experiment exists before evaluation completes. This fixes the 404 error when nbSamples=0. Co-Authored-By: Claude Opus 4.5 <[email protected]>

petrotiurin

Great change, thanks for putting it together so quickly!

apps/opik-documentation/documentation/fern/docs/evaluation/manage_datasets.mdx

sdks/typescript/src/opik/dataset/Dataset.ts

sdks/typescript/src/opik/dataset/DatasetVersion.ts

…IK-4149-dataset-versions-ts-sdk

petrotiurin

Apart from this, looks good!

apps/opik-documentation/documentation/fern/docs/evaluation/manage_datasets.mdx

Remove the shorter duplicate "Working with dataset versions programmatically" section and add a TypeScript tab to the remaining detailed section. Co-Authored-By: Claude Opus 4.6 <[email protected]>

baz-reviewer · 2026-02-09T15:05:11Z

sdks/typescript/src/opik/dataset/getDatasetItems.ts

+    const streamResponse = await opik.api.datasets.streamDatasetItems({
+      datasetName,
+      lastRetrievedId: currentLastId,
+      steamLimit: streamLimit,
+      datasetVersion,
+    });


streamDatasetItems is called with steamLimit instead of streamLimit, so the server never sees the requested batch size and ignores nbSamples/remaining adjustments; can we send the correctly spelled streamLimit key so limits actually work?

Suggested change

const streamResponse = await opik.api.datasets.streamDatasetItems({

datasetName,

lastRetrievedId: currentLastId,

steamLimit: streamLimit,

datasetVersion,

});

const streamResponse = await opik.api.datasets.streamDatasetItems({

datasetName,

lastRetrievedId: currentLastId,

streamLimit: streamLimit,

datasetVersion,

});

_{Finding type: Design extensible API interfaces}

* [OPIK-4149] [SDK] Add DatasetVersion support to TypeScript SDK Add dataset versioning capabilities allowing users to work with specific snapshots of datasets. This enables reproducible evaluations by pinning to a specific version. Changes: - Add DatasetVersion class for read-only version views - Add Dataset.getVersionView(), getCurrentVersionName(), getVersionInfo() - Support DatasetVersion in evaluate() with version tracking - Add DatasetVersionNotFoundError for version lookup failures - Export Dataset, DatasetVersion, DatasetVersionNotFoundError from SDK - Add comprehensive unit tests (32 tests) and integration tests (3 tests) * Address PR review comments - Remove redundant if wrapper in toJson keysMapping loop - Export DatasetVersionPublic type from SDK public API - Update test imports to use public SDK exports Co-Authored-By: Claude Opus 4.5 <[email protected]> * Add DatasetVersion documentation to TypeScript SDK - Add "Working with Dataset Versions" section to datasets.mdx with examples for getVersionView, getCurrentVersionName, and getVersionInfo methods - Document DatasetVersion class properties and methods in API reference - Update evaluate.mdx to show Dataset | DatasetVersion parameter type - Add TypeScript version selection example to manage_datasets.mdx Co-Authored-By: Claude Opus 4.5 <[email protected]> * Fix DatasetVersion to use versionHash for item streaming The backend's resolveVersionId method looks up versions by hash or tag, not by versionName. Changed to pass versionHash instead of versionName to match Python SDK behavior and fix E2E test failures. Co-Authored-By: Claude Opus 4.5 <[email protected]> * Fix E2E test for DatasetVersion evaluation Add scoringKeyMapping to map 'expected' to 'expected_output' field in the dataset items, matching the pattern used in other evaluation tests. Co-Authored-By: Claude Opus 4.5 <[email protected]> * Add lastRetrievedId parameter to DatasetVersion.getItems for pagination parity Adds the lastRetrievedId parameter to DatasetVersion.getItems() to match the Dataset.getItems() API. This allows manual pagination for datasets with more than 2000 items. Co-Authored-By: Claude Opus 4.5 <[email protected]> * Add auto-pagination to Dataset and DatasetVersion getItems methods This adds automatic pagination support for retrieving large datasets: - Dataset.getItemsAsDataclasses() now fetches all items automatically - DatasetVersion.getItemsAsDataclasses() uses the same pagination pattern - Both use cursor-based pagination with lastRetrievedId - Maximum batch size of 2000 items per request (API limit) - Pagination continues until all requested items are retrieved This provides parity with the Python SDK's auto-pagination behavior. Co-Authored-By: Claude Opus 4.5 <[email protected]> * Fix nbSamples=0 edge case in Dataset and DatasetVersion getItems Return empty array immediately when nbSamples === 0 to avoid API call with invalid steamLimit = 0 (API requires steamLimit >= 1). Co-Authored-By: Claude Opus 4.5 <[email protected]> * Apply conciseness improvements from code review Simplify streamLimit calculation using nullish coalescing operator. Co-Authored-By: Claude Opus 4.5 <[email protected]> * Fix race condition in experiment creation Add await to createExperiment API call to ensure experiment exists before evaluation completes. This fixes the 404 error when nbSamples=0. Co-Authored-By: Claude Opus 4.5 <[email protected]> * OPIK-4149 refactor * OPIK-4149 Merge duplicate dataset versions docs sections Remove the shorter duplicate "Working with dataset versions programmatically" section and add a TypeScript tab to the remaining detailed section. Co-Authored-By: Claude Opus 4.6 <[email protected]> --------- Co-authored-by: Claude Opus 4.5 <[email protected]>

awkoy requested a review from a team as a code owner February 4, 2026 16:36

github-actions bot assigned awkoy Feb 4, 2026

github-actions bot added tests Including test files, or tests related like configuration. typescript *.ts *.tsx TypeScript SDK labels Feb 4, 2026

baz-reviewer bot reviewed Feb 4, 2026

View reviewed changes

sdks/typescript/src/opik/dataset/DatasetVersion.ts Outdated Show resolved Hide resolved

sdks/typescript/src/opik/dataset/DatasetVersion.ts Outdated Show resolved Hide resolved

sdks/typescript/tests/dataset/datasetVersion.test.ts Show resolved Hide resolved

awkoy and others added 2 commits February 5, 2026 12:34

Address PR review comments

b4eff96

- Remove redundant if wrapper in toJson keysMapping loop - Export DatasetVersionPublic type from SDK public API - Update test imports to use public SDK exports Co-Authored-By: Claude Opus 4.5 <[email protected]>

awkoy force-pushed the awkoy/OPIK-4149-dataset-versions-ts-sdk branch from 4a177a7 to b4eff96 Compare February 5, 2026 11:34

awkoy requested a review from a team as a code owner February 5, 2026 11:52

github-actions bot added the documentation Improvements or additions to documentation label Feb 5, 2026

baz-reviewer bot reviewed Feb 5, 2026

View reviewed changes

awkoy and others added 2 commits February 5, 2026 14:36

Fix E2E test for DatasetVersion evaluation

f39442d

Add scoringKeyMapping to map 'expected' to 'expected_output' field in the dataset items, matching the pattern used in other evaluation tests. Co-Authored-By: Claude Opus 4.5 <[email protected]>

github-actions bot added the dependencies Pull requests that update a dependency file label Feb 5, 2026

baz-reviewer bot reviewed Feb 5, 2026

View reviewed changes

sdks/typescript/src/opik/dataset/Dataset.ts Outdated Show resolved Hide resolved

sdks/typescript/src/opik/dataset/DatasetVersion.ts Outdated Show resolved Hide resolved

Fix nbSamples=0 edge case in Dataset and DatasetVersion getItems

2fd0c92

Return empty array immediately when nbSamples === 0 to avoid API call with invalid steamLimit = 0 (API requires steamLimit >= 1). Co-Authored-By: Claude Opus 4.5 <[email protected]>

baz-reviewer bot reviewed Feb 5, 2026

View reviewed changes

sdks/typescript/src/opik/dataset/Dataset.ts Outdated Show resolved Hide resolved

awkoy and others added 2 commits February 5, 2026 17:58

Apply conciseness improvements from code review

13b9dd7

Simplify streamLimit calculation using nullish coalescing operator. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Fix race condition in experiment creation

734cc0a

Add await to createExperiment API call to ensure experiment exists before evaluation completes. This fixes the 404 error when nbSamples=0. Co-Authored-By: Claude Opus 4.5 <[email protected]>

petrotiurin reviewed Feb 6, 2026

View reviewed changes

awkoy added 2 commits February 9, 2026 12:57

OPIK-4149 refactor

50111c1

Merge branch 'main' of https://github.com/comet-ml/opik into awkoy/OP…

01bd6f1

…IK-4149-dataset-versions-ts-sdk

petrotiurin reviewed Feb 9, 2026

View reviewed changes

apps/opik-documentation/documentation/fern/docs/evaluation/manage_datasets.mdx Show resolved Hide resolved

OPIK-4149 Merge duplicate dataset versions docs sections

ecbb6fa

Remove the shorter duplicate "Working with dataset versions programmatically" section and add a TypeScript tab to the remaining detailed section. Co-Authored-By: Claude Opus 4.6 <[email protected]>

petrotiurin approved these changes Feb 9, 2026

View reviewed changes

awkoy merged commit 0cdca8c into main Feb 9, 2026
17 checks passed

awkoy deleted the awkoy/OPIK-4149-dataset-versions-ts-sdk branch February 9, 2026 15:04

baz-reviewer bot reviewed Feb 9, 2026

View reviewed changes

[OPIK-4149] [SDK] Add DatasetVersion support to TypeScript SDK #5068

[OPIK-4149] [SDK] Add DatasetVersion support to TypeScript SDK #5068

Uh oh!

Conversation

awkoy commented Feb 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Details

Change checklist

Issues

Documentation

Testing

Uh oh!

github-actions bot commented Feb 4, 2026

📋 PR Linter Failed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 5, 2026

📋 PR Linter Failed

Uh oh!

github-actions bot commented Feb 5, 2026

📋 PR Linter Failed

Uh oh!

github-actions bot commented Feb 5, 2026

📋 PR Linter Failed

Uh oh!

github-actions bot commented Feb 5, 2026

📋 PR Linter Failed

Uh oh!

github-actions bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

petrotiurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

petrotiurin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

baz-reviewer bot Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

awkoy commented Feb 4, 2026 •

edited

Loading

github-actions bot commented Feb 5, 2026 •

edited

Loading