Skip to content

Add bt datasets snapshots for dataset version control#176

Draft
max-braintrust wants to merge 4 commits intomainfrom
max/add-dataset-snapshots
Draft

Add bt datasets snapshots for dataset version control#176
max-braintrust wants to merge 4 commits intomainfrom
max/add-dataset-snapshots

Conversation

@max-braintrust
Copy link
Copy Markdown

TL;DR

Follow up to: #104
Added bt datasets snapshots for managing saved dataset snapshots, plus a BTQL structured query fix needed by dataset row previews and snapshot creation.

What changed?

Added dataset snapshot management functionality:

  • New bt datasets snapshots command with subcommands: list, create, and restore
  • Uses snapshot/dataset snapshot terminology to match the UI
  • Snapshot listing displays saved snapshots for a dataset
  • Snapshot restore supports restore by snapshot name or by xact ID with --snapshot
  • Restore includes preview support and requires confirmation unless --force is passed
  • JSON output includes snapshot/create/restore modes and found_existing for create responses
  • Moved snapshot-specific CLI args into the snapshot module to match existing subcommand patterns
  • Added shared profile utilities for resolving profile info and generating default name slugs

Fixed dataset BTQL structured queries:

Updated structured BTQL select entries to use the current schema with expr and alias
Fixed bt datasets view failures caused by the older shorthand select shape
Added a constrained _xact_id BTQL query for snapshot creation when inferring the current dataset head
Kept required BTQL safety filters on dataset row/head queries

# To see the current issue with BTQL structured queries: 
curl -fsSL https://bt.dev/cli/install.sh | bash -s -- --canary
bt datasets view --json # select a dataset, you should see a 400 bad request a Zod parser error.

Added test coverage:

Unit tests for snapshot arg parsing, read/write auth routing, response deserialization, and restore target selection
Fixture coverage for snapshot creation, duplicate xact handling via x-bt-found-existing, and snapshot listing
Mock server support for dataset snapshot create and list endpoints

How to test?

# Create a dataset
bt datasets create my-dataset --rows '[{"id":"case-1","input":{"text":"hi"},"expected":"hello"}]'

# List snapshots
bt datasets snapshots list my-dataset

# Create a snapshot
bt datasets snapshots create my-dataset baseline

# Re-run create for the same xact to verify found_existing handling
bt datasets snapshots create my-dataset baseline-again --xact-id 1000192656880881099 --json

# Restore by snapshot name
bt datasets snapshots restore my-dataset --name baseline

# Restore by xact ID
bt datasets snapshots restore my-dataset --snapshot 1000192656880881099 --force

Why make this change?

This gives users CLI access to the same saved dataset snapshot workflow used in the UI. It makes it possible to save, inspect, and restore dataset states without leaving the terminal. The BTQL fix also unblocks dataset viewing and snapshot head-xact inference against the current structured query schema.

@max-braintrust max-braintrust changed the title Add bt datasets snapshots for better dataset version control Add bt datasets snapshots for dataset version control May 6, 2026
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 6, 2026

Latest downloadable build artifacts for this PR commit 2364e75c67be:

Available artifact names
  • ``artifacts-build-global
  • ``artifacts-build-local-x86_64-apple-darwin
  • ``artifacts-build-local-x86_64-pc-windows-msvc
  • ``artifacts-build-local-aarch64-pc-windows-msvc
  • ``artifacts-build-local-x86_64-unknown-linux-musl
  • ``artifacts-build-local-x86_64-unknown-linux-gnu
  • ``artifacts-build-local-aarch64-apple-darwin
  • ``artifacts-build-local-aarch64-unknown-linux-gnu
  • ``artifacts-plan-dist-manifest
  • ``cargo-dist-cache

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant