[NA] [SDK] CLI import/export improvements

[dsblank]

Details

This PR improves the opik import and opik export CLI commands across several dimensions: new bulk commands, fidelity of round-trips, correctness fixes, a major performance improvement for large re-exports, and OQL trace filtering across all export commands.

New: --filter on opik export experiment and opik export all

The OQL filter flag (previously only on opik export project) now works on all commands that export traces.

# Export project traces after a given date (existing)
opik export my-workspace project "my-project" --filter 'created_at >= "2024-01-01T00:00:00Z"'

# Export experiment traces after a given date (new)
opik export my-workspace experiment "my-experiment" --filter 'created_at >= "2024-01-01T00:00:00Z"'

# Export all traces in a date range across the whole workspace (new)
opik export my-workspace all --filter 'created_at >= "2024-01-01T00:00:00Z" AND created_at < "2024-04-01T00:00:00Z"'

For project exports the filter is evaluated server-side (unchanged). For experiment and all (experiment phase), traces are fetched by pre-known IDs so filtering is applied client-side after each trace is retrieved, using a new matches_trace_filter() helper in utils.py that evaluates OQL expressions against trace dicts (handles date_time, number, and string fields, including nested key access).

New: opik export <workspace> all and opik import <workspace> all

Both CLI groups now have an all subcommand that operates on every data type in a workspace (datasets, prompts, projects/traces, and experiments) in a single command.

# Export everything
opik export my-workspace all

# Export only selected types
opik export my-workspace all --include datasets,prompts

# Import everything (resumes automatically if interrupted)
opik import my-workspace all

# Dry-run to preview what would be imported
opik import my-workspace all --dry-run

New: Resumable, incremental project exports (ExportManifest)

Re-running opik export … project on a large project previously required paginating through every trace via the API. A new ExportManifest (SQLite/WAL, stored as export_manifest.db alongside the trace files) tracks download state across runs:

Scenario	Behaviour
Second run, nothing new	Adds a created_at >= last_exported_at − 5 min filter; fetches 0–1 API pages
Aborted / interrupted run	Status remains in_progress; next run loads already-downloaded IDs from the DB and skips them
No manifest yet	Scans the directory once and seeds the manifest so old files are not re-downloaded
--force	Resets the manifest and re-downloads everything
Format switch (json ↔ csv)	Detects mismatch, resets manifest, re-downloads in the new format

Fix: PromptType case sensitivity during import

Exported prompt types are uppercased ("MUSTACHE", "JINJA2") but the PromptType enum uses lowercase values. The importer now tries the lowercased value first and falls back gracefully.

Fix: Thread-safe project name cache in experiment export

Fixed a race condition in export_traces_by_ids where two threads racing on the same project_id cache miss could both issue a redundant get_project API call. Fixed with a threading.Lock + dict.setdefault.

Fix: Retry on 429 and honour Retry-After header

429 Too Many Requests is now retried; a Retry-After header causes the client to wait exactly that long before retrying.

Improvement: Preserve read-only fields across import/export round-trips

Fields such as created_at, created_by, last_updated_at, and last_updated_by are stored under _import_* keys in metadata so the information survives a round-trip.

Issues

N/A

Testing

• opik export <workspace> all exports datasets, prompts, projects, and experiments to the expected directory layout
• opik import <workspace> all imports the exported tree back; verify counts match
• Re-running opik export … project on a project with no new traces completes in seconds and reports all traces skipped
• Killing an export mid-run and re-running resumes from where it left off without re-downloading completed traces
• Importing a prompt exported as type "MUSTACHE" succeeds without a warning
• A 429 response from the API is retried; a Retry-After: 5 header causes a ~5 s wait before the retry
• opik export … experiment --filter 'created_at >= "2024-01-01T00:00:00Z"' exports only matching traces
• opik export … all --filter 'created_at >= "2024-01-01T00:00:00Z"' filters traces in both projects and experiments phases

Documentation

• Updated import_export_commands.mdx: documents --filter on experiment and all, adds opik export all options, adds date-range filter examples

Change checklist

• I have considered the possibility of backwards incompatible changes and mitigated them if necessary
• I have added tests where required
• All pre-existing tests pass

[github-actions]

🌿 Preview your docs: https://opik-preview-71792b5e-9ac1-41a2-b203-07856414d62b.docs.buildwithfern.com/docs/opik

No broken links found

---

📌 Results for commit 11ef58c

[github-actions]

SDK E2E Tests Results

0 tests   0 ✅  0s ⏱️
0 suites  0 💤
0 files    0 ❌

Results for commit 27465ac.

[github-actions]

Python SDK Unit Tests Results (Python 3.11)

2 319 tests   2 319 ✅  46s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK Unit Tests Results (Python 3.13)

2 319 tests   2 319 ✅  51s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK Unit Tests Results (Python 3.12)

2 319 tests   2 319 ✅  51s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK Unit Tests Results (Python 3.10)

2 319 tests   2 319 ✅  51s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK Unit Tests Results (Python 3.14)

2 319 tests   2 319 ✅  36s ⏱️
    1 suites      0 💤
    1 files        0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK E2E Tests Results (Python 3.13)

244 tests   242 ✅  9m 0s ⏱️
  1 suites    2 💤
  1 files      0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK E2E Tests Results (Python 3.12)

244 tests   242 ✅  9m 54s ⏱️
  1 suites    2 💤
  1 files      0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK E2E Tests Results (Python 3.11)

244 tests   242 ✅  8m 50s ⏱️
  1 suites    2 💤
  1 files      0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[github-actions]

Python SDK E2E Tests Results (Python 3.14)

244 tests   242 ✅  9m 3s ⏱️
  1 suites    2 💤
  1 files      0 ❌

Results for commit 6756408.

♻️ This comment has been updated with latest results.

[baz-reviewer]

ExportManifest._open duplicates MigrationManifest._open's WAL/synchronous setup and schema creation, should we extract the shared manifest plumbing into a base class or helper?

_{Finding type: Code Dedup and Conventions | Severity: 🟢 Low}

---

Want Baz to fix this for you? Activate Fixer

[baz-reviewer]

Should we make the fast-path guard compare trace_page.total only against downloads matching the current filter or skip the fast-path on filter change instead of comparing to project-wide len(already_downloaded)?

_{Finding type: Logical Bugs | Severity: 🔴 High}

---

Want Baz to fix this for you? Activate Fixer

Other fix methods

Prompt for AI Agents:

Before applying, verify this suggestion against the current code. In
sdks/python/src/opik/cli/exports/project.py around lines 222 to 237, the fast-path in
export_traces incorrectly compares trace_page.total against a project-wide
already_downloaded set even when a new filter is applied. Change the guard so the
fast-path is only executed when the current parsed_filter is None OR when a manifest is
provided and the manifest explicitly records the same filter (or filter fingerprint) as
the current parsed_filter; otherwise skip the fast-path. Concretely, check manifest is
not None and manifest.get_filter() == parsed_filter before using api_total <=
len(already_downloaded); if that condition fails, do not break early and continue normal
pagination. This avoids skipping work when the filter changed.

[baz-reviewer]

ThreadPoolExecutor(max_workers=max_workers) is fed the entire all_projects list at once, should we limit pending submissions by wrapping submit in a bounded semaphore or submitting in small batches?

_{Finding type: Prefer non-blocking concurrency | Severity: 🔴 High}

---

Want Baz to fix this for you? Activate Fixer

Other fix methods

Prompt for AI Agents:

Before applying, verify this suggestion against the current code. In
sdks/python/src/opik/cli/exports/all.py around lines 288 to 305, the code in
_export_all_projects currently submits every project to ThreadPoolExecutor via a dict
comprehension which queues a future for every project at once (unbounded work queue).
Refactor by replacing the comprehension with an explicit submission loop that uses a
bounded threading.Semaphore (e.g. semaphore = threading.Semaphore(max_workers * 2)),
call semaphore.acquire() before each executor.submit(), add a done callback on the
future to semaphore.release(), and store future->project in the mapping as you go. This
will apply backpressure and prevent unbounded queued tasks; keep the existing
as_completed consumption logic unchanged.

[baz-reviewer]

_export_all_projects and _export_all_experiments swallow exceptions from future.result() and only print, allowing opik export … all to exit 0 despite failures — should we re-raise or let errors bubble so the CLI fails fast?

_{Finding type: Centralize error handling | Severity: 🔴 High}

---

Want Baz to fix this for you? Activate Fixer

Other fix methods

Prompt for AI Agents:

Before applying, verify this suggestion against the current code. In
sdks/python/src/opik/cli/exports/all.py around lines 304 to 321, the
_export_all_projects function currently swallows exceptions from future.result() — it
only logs errors and continues, which allows the CLI to exit 0 even when exports failed.
Refactor by introducing a local had_errors boolean (or capture the first exception)
outside the as_completed loop, set it to True (or store the exception) inside the except
Exception block, and after the as_completed loop but before returning, raise a
RuntimeError (or re-raise the captured exception) if had_errors is True so the CLI fails
non‑zero on worker failures. Apply the same pattern to the _export_all_experiments
export loop (the analogous try/except around future.result()), ensuring both functions
propagate fatal worker errors instead of silently logging them.

[baz-reviewer]

batch_fetch_failures treats _fetch_trace_data None results as failures and blocks manifest.complete(), should we treat those None results as skips and exclude them from failed_count?

_{Finding type: Logical Bugs | Severity: 🔴 High}

---

Want Baz to fix this for you? Activate Fixer

Other fix methods

Prompt for AI Agents:

Before applying, verify this suggestion against the current code. In
sdks/python/src/opik/cli/exports/experiment.py around lines 324-351, inside
export_traces_by_ids, the code treats _fetch_trace_data returning None as a fetch
failure and later includes those in failed_count, preventing manifest.complete() from
running. Change the fetch-collection logic so that when a fetch future returns None it
increments a local 'batch_filter_skipped' (or similar) and is NOT added to
fetched_traces and NOT counted as a fetch failure; compute batch_fetch_failures as
(len(batch_trace_ids) - len(fetched_traces) - batch_filter_skipped) so only true fetch
exceptions are counted, and ensure failed_count is increased only by those real fetch
exceptions. This will allow manifest.complete() to run when only
project-metadata-missing traces were skipped.

[baz-reviewer]

fetch_future.result() is caught and only printed under debug — should we log or rethrow so failures aren't silently swallowed?

_{Finding type: Centralize error handling | Severity: 🟠 Medium}

---

Want Baz to fix this for you? Activate Fixer

Other fix methods

Prompt for AI Agents:

Before applying, verify this suggestion against the current code. In
sdks/python/src/opik/cli/exports/experiment.py around lines 341 to 345 inside the
export_traces_by_ids function (the fetch-as_completed loop), the current except
Exception block only prints errors when debug is true, causing fetch failures to be
silently swallowed. Change this block to always log the failure at error (or warning)
level including the trace_id and exception details (use the existing console or a module
logger), and increment the outer failed_count to record a fetch failure for centralized
monitoring. Do not re-raise the exception so other fetches continue, but ensure the
message is emitted even when debug is False and includes enough context (trace_id,
exception type/message, and optionally a stacktrace) for diagnostics.