Manage datasets - Braintrust

After creating a dataset, you’ll typically organize, version, and modify it over time. Use the UI to tag, snapshot, and validate datasets at the dataset level, and use the SDK or the bt CLI to filter and edit individual records.

Organize datasets

Tag and star datasets

You can tag and star datasets to organize and find them in the datasets list. Tagging a dataset adds metadata that can be used to filter and group records, while starring a dataset causes it to sort first in the datasets table and dataset picker dropdowns. To tag datasets:

Go to Datasets.
Select one or more datasets.
Click Tag in the toolbar.
Select or create tags to apply.

Tags are configured at the project level and shared across all objects — logs, experiments, dataset records, and entire datasets. See project tag settings.

To star a dataset, click the star icon next to the dataset’s name in the datasets list.

Save snapshots

only available on Pro and Enterprise plans.

Snapshots are named checkpoints of a dataset at a specific point in time. Save a snapshot to preserve the current state before making changes, or to pin a specific version for experiments and environments.

Go to Datasets.
Open your dataset.
Click Snapshots > + Save snapshot in the toolbar. This option is available only when the dataset is non-empty and has changed since the last snapshot was saved.

From the Snapshots dropdown, you can also:

Rename: Give the snapshot a descriptive name.
View: Open the snapshot in a read-only viewer.
Evaluate in experiment or Evaluate in playground: Run an eval using the snapshot’s data.
Environments: Assign the snapshot to one or more environments. See Assign to environments.
Restore: Roll the dataset back to the snapshot’s state.
Delete: Permanently remove the snapshot.

To create a snapshot, fetch a row from the dataset to get the current xact_id, then call POST /v1/dataset_snapshot. The dataset must be non-empty — an empty dataset has no xact_id to snapshot.

const datasetId = "<your-dataset-id>";

// Fetch a row to get the current xact_id
const fetchResp = await fetch(
  `https://api.braintrust.dev/v1/dataset/${datasetId}/fetch?limit=1`,
  { headers: { Authorization: `Bearer ${process.env.BRAINTRUST_API_KEY}` } },
);
const { events } = await fetchResp.json();
if (events.length === 0) {
  throw new Error("Cannot create a snapshot of an empty dataset.");
}
const xactId = events[0]._xact_id;

// Create the snapshot
await fetch("https://api.braintrust.dev/v1/dataset_snapshot", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BRAINTRUST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ dataset_id: datasetId, name: "my-snapshot", xact_id: xactId }),
});

import os
import httpx

dataset_id = "<your-dataset-id>"

# Fetch a row to get the current xact_id
resp = httpx.get(
    f"https://api.braintrust.dev/v1/dataset/{dataset_id}/fetch",
    params={"limit": 1},
    headers={"Authorization": f"Bearer {os.environ['BRAINTRUST_API_KEY']}"},
)
events = resp.json()["events"]
if not events:
    raise ValueError("Cannot create a snapshot of an empty dataset.")
xact_id = events[0]["_xact_id"]

# Create the snapshot
httpx.post(
    "https://api.braintrust.dev/v1/dataset_snapshot",
    json={"dataset_id": dataset_id, "name": "my-snapshot", "xact_id": xact_id},
    headers={"Authorization": f"Bearer {os.environ['BRAINTRUST_API_KEY']}"},
)

Use GET /v1/dataset_snapshot, PATCH /v1/dataset_snapshot/{id}, and DELETE /v1/dataset_snapshot/{id} to list, rename, and delete snapshots.

Use bt datasets snapshots to create, list, restore, and delete snapshots from the CLI:

# Snapshot the dataset's current state
bt datasets snapshots create my-dataset baseline

# List saved snapshots
bt datasets snapshots list my-dataset

# Restore the dataset to a snapshot
bt datasets snapshots restore my-dataset --name baseline

# Delete a snapshot
bt datasets snapshots delete my-dataset baseline

See the bt datasets snapshots reference for all flags.

You can also save, list, and restore snapshots from Loop when working on a dataset page.

Define schemas

If you want to ensure all records have the same structure or make editing easier, define JSON schemas for your dataset fields. Schemas are particularly useful when multiple team members are manually adding records or when you need strict data validation. Dataset schemas enable:

Validation: Catch structural errors when adding or editing records.
Form-based editing: Edit records with intuitive forms instead of raw JSON.
Documentation: Make field expectations explicit for your team.

To define a schema:

Go to Datasets.
Open your dataset.
Click Field schemas in the toolbar.
Select the field you want to define a schema for (input, expected, or metadata).
Click Infer schema to automatically generate a schema from the first 100 records, or manually define your schema structure.
Toggle Enforce to enable validation. When enabled:
- New records must conform or show validation errors.
- Existing non-conforming records display warnings.
- Form editing validates input as you type.

Enforcement is UI-only and doesn’t affect SDK inserts or updates.

Edit datasets

Read, update, and delete individual records programmatically.

Filter records

Filter dataset records using the Filter button in the dataset table. You can filter by any field — input, expected, metadata, tags, or scores — using SQL expressions.

Go to Datasets and open your dataset.
Click Filter.
Add one or more filter conditions.

When you create an experiment from a filtered dataset view, the active filters are carried over so the run is scoped to the same subset of records.

Read and filter datasets using _internal_btql to control which records are returned:

import { initDataset } from "braintrust";

// Read all records
const dataset = initDataset("My App", { dataset: "Customer Support" });

for await (const row of dataset) {
  console.log(row);
}

// Filter by metadata
const premiumDataset = initDataset("My App", {
  dataset: "Customer Support",
  _internal_btql: {
    filter: { btql: "metadata.category = 'premium'" },
    limit: 100,
  },
});

for await (const row of premiumDataset) {
  console.log(row);
}

// Sort by creation date
const sortedDataset = initDataset("My App", {
  dataset: "Customer Support",
  _internal_btql: {
    sort: [{ expr: { btql: "created" }, dir: "desc" }],
    limit: 50,
  },
});

// Combine filters and sorts
const recentSupport = initDataset("My App", {
  dataset: "Customer Support",
  _internal_btql: {
    filter: {
      btql: "metadata.category = 'support' and created > now() - interval 7 day",
    },
    sort: [{ expr: { btql: "created" }, dir: "desc" }],
    limit: 1000,
  },
});

import braintrust

# Read all records
dataset = braintrust.init_dataset(project="My App", name="Customer Support")

for row in dataset:
    print(row)

# Filter by metadata
premium_dataset = braintrust.init_dataset(
    project="My App",
    name="Customer Support",
    _internal_btql={
        "filter": {"btql": "metadata.category = 'premium'"},
        "limit": 100,
    },
)

for row in premium_dataset:
    print(row)

# Sort by creation date
sorted_dataset = braintrust.init_dataset(
    project="My App",
    name="Customer Support",
    _internal_btql={
        "sort": [{"expr": {"btql": "created"}, "dir": "desc"}],
        "limit": 50,
    },
)

# Combine filters and sorts
recent_support = braintrust.init_dataset(
    project="My App",
    name="Customer Support",
    _internal_btql={
        "filter": {"btql": "metadata.category = 'support' and created > now() - interval 7 day"},
        "sort": [{"expr": {"btql": "created"}, "dir": "desc"}],
        "limit": 1000,
    },
)

For more information on SQL syntax and available operators, see the SQL reference documentation.

Update records

Update existing records by id:

import { initDataset } from "braintrust";

const dataset = initDataset("My App", { dataset: "Customer Support" });

// Insert a record
const id = dataset.insert({
  input: { question: "How do I reset my password?" },
  expected: { answer: "Click 'Forgot Password' on the login page." },
});

// Update the record
dataset.update({
  id,
  metadata: { reviewed: true, difficulty: "easy" },
});

await dataset.flush();

import braintrust

dataset = braintrust.init_dataset(project="My App", name="Customer Support")

# Insert a record
id = dataset.insert(
    input={"question": "How do I reset my password?"},
    expected={"answer": "Click 'Forgot Password' on the login page."},
)

# Update the record
dataset.update(
    id=id,
    metadata={"reviewed": True, "difficulty": "easy"},
)

dataset.flush()

The update() method applies a merge strategy: only the fields you provide will be updated, and all other existing fields in the record will remain unchanged.

Use the bt datasets update CLI command (also available as add and refresh) to upsert records by stable ID:

bt datasets update my-dataset --file records.jsonl
bt datasets add my-dataset --rows '[{"id":"case-2","input":{"text":"bye"},"expected":"goodbye"}]'
bt datasets refresh my-dataset --file records.jsonl --id-field metadata.case_id

Flag	Description
`--file <PATH>`	Input JSONL file
`--rows <JSON>`	Inline JSON array of rows
`--id-field <PATH>`	Dot-separated path to use as the record ID instead of the `id` field

Each row must have a stable ID via the id field or --id-field. Rows without IDs are rejected.These commands upsert rows directly — rows not in the input are not deleted. refresh fails if the dataset does not exist.Use --id-field to extract an ID from a nested field (e.g., metadata.case_id). Escape literal dots as \. and literal backslashes as \\.

Delete records

To delete specific records:

Go to Datasets and open your dataset.
Select the records you want to delete.
Click Delete in the toolbar.

To delete an entire dataset:

Go to Datasets.
Select the dataset you want to delete.
Click Delete in the toolbar.

Remove individual records by id:

import { initDataset } from "braintrust";

const dataset = initDataset("My App", { dataset: "Customer Support" });

// Insert a record
const id = dataset.insert({
  input: { question: "Test question" },
  expected: { answer: "Test answer" },
});

// Delete the record
await dataset.delete(id);
await dataset.flush();

import braintrust

dataset = braintrust.init_dataset(project="My App", name="Customer Support")

# Insert a record
id = dataset.insert(
    input={"question": "Test question"},
    expected={"answer": "Test answer"},
)

# Delete the record
dataset.delete(id)
dataset.flush()

Use the bt datasets delete CLI command to delete a dataset and all its records. To delete individual records, use the UI or the SDK.

bt datasets delete my-dataset

This operation is irreversible. All records in the dataset are permanently deleted.

Flush records

The Braintrust SDK flushes records asynchronously and installs exit handlers, but these hooks are not always respected (e.g., by certain runtimes or when exiting a process abruptly). Call flush() to ensure records are written:

import { initDataset } from "braintrust";

const dataset = initDataset("My App", { dataset: "Customer Support" });

// Insert records
dataset.insert({
  input: { question: "How do I reset my password?" },
  expected: { answer: "Click 'Forgot Password' on the login page." },
});

// Flush to ensure all records are saved
await dataset.flush();

import braintrust

dataset = braintrust.init_dataset(project="My App", name="Customer Support")

# Insert records
dataset.insert(
    input={"question": "How do I reset my password?"},
    expected={"answer": "Click 'Forgot Password' on the login page."},
)

# Flush to ensure all records are saved
dataset.flush()

Review datasets

You can configure human review workflows to label and evaluate dataset records with your team.

Configure review scores

Configure categorical scores to allow reviewers to rapidly label records. See Configure review scores for details.

Assign rows for review

Assign dataset rows to team members for review, analysis, or follow-up action. Assignments are particularly useful for distributing review work across multiple team members. See Assign rows for review for details.

Create custom dataset views

Custom dataset views let you build tailored interfaces for reviewing individual dataset rows. Open a dataset row, select Views, and describe the interface you want in natural language. Loop generates a customizable React component your team can use directly in Braintrust. See Custom dataset views for guidance on creating, editing, and sharing views.

Customize table views

Tailor how dataset data is displayed in the UI by adding computed columns, saving custom views, and sharing views across projects.

Create custom columns

Extract values from records using custom columns. Use SQL expressions to surface important fields directly in the table.

Create custom table views

To create or update a custom table view:

Apply the filters and display settings you want.
Open the menu and select Save view… or Save view as….

Custom table views are visible to all project members. Creating or editing a table view requires the Update project permission.

Set default table views

You can set default views at three levels:

Organization default: Visible to all members when they open the page. This applies per page. For example, you can set separate organization defaults for Logs, Experiments, and Review. To set an organization default, you need the Manage settings organization permission (included by default in the Owner role). See Access control for details.
Project default: Overrides the organization default for everyone viewing this project. To set a project default, you need the project-level Update permission. Project admins can set project defaults even without organization-level permissions. See Access control for details.
Personal default: Overrides the project and organization defaults for you only. Personal defaults are stored in your browser, so they do not carry over across devices or browsers.

To set a default view:

Switch to the view you want by selecting it from the menu.
Open the menu again and hover over the currently selected view to reveal its submenu.
Choose Set as personal default view, Set as project default view, or Set as organization default view.

To clear a default view:

Open the menu and hover over the currently selected view to reveal its submenu.
Choose Clear personal default view, Clear project default view, or Clear organization default view.

Default view settings are mutually exclusive on a given view. Setting one type of default on a view automatically clears any other default that was previously set on the same view. When a user opens a page, Braintrust loads the first match in this order: personal default, project default, organization default, then the standard “All …” view (for example, “All logs view”).

Duplicate table views across projects

If you’ve built a useful custom table view in one project, you can duplicate it to another project via the API rather than recreating it from scratch. Datasets have two customizable views:

Datasets list: The project’s Datasets tab, where each row is a dataset.
Single dataset table: The rows of data inside one dataset.

The following steps work for either. Choose the corresponding view_type in the API call.

Use the list views API endpoint to fetch the dataset views in your source project. Pass the following query parameters:

object_type=project
object_id=<source-project-id>
view_type=dataset for a single dataset table view, or view_type=datasets for the datasets list

curl --request GET \
  --url 'https://api.braintrust.dev/v1/view?object_type=project&object_id=<source-project-id>&view_type=dataset' \
  --header 'Authorization: Bearer <your-api-key>'

curl --request GET \
  --url 'https://api.braintrust.dev/v1/view?object_type=project&object_id=<source-project-id>&view_type=datasets' \
  --header 'Authorization: Bearer <your-api-key>'

In the response, find the view you want to duplicate and copy its view_data and options payloads.

Use the create view API endpoint to create the view in the destination project. Set object_id to the destination project ID.

curl --request POST \
  --url https://api.braintrust.dev/v1/view \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '
  {
    "object_type": "project",
    "object_id": "<destination-project-id>",
    "view_type": "dataset",
    "name": "<new-view-name>",
    "view_data": <view-data-payload>,
    "options": <options-payload>
  }'

curl --request POST \
  --url https://api.braintrust.dev/v1/view \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data '
  {
    "object_type": "project",
    "object_id": "<destination-project-id>",
    "view_type": "datasets",
    "name": "<new-view-name>",
    "view_data": <view-data-payload>,
    "options": <options-payload>
  }'

Copy a dataset’s URL from your browser to share it. For a portable link that resolves regardless of organization or project, use its ID:

https://www.braintrust.dev/app/object?object_type=dataset&object_id=<dataset_id>

Visiting this URL redirects to the dataset’s canonical page.

Next steps

Use datasets in evaluations with Eval().
Track performance across experiments.

​Organize datasets

​Tag and star datasets

​Save snapshots

​Define schemas

​Edit datasets

​Filter records

​Update records

​Delete records

​Flush records

​Review datasets

​Configure review scores

​Assign rows for review

​Create custom dataset views

​Customize table views

​Create custom columns

​Create custom table views

​Set default table views

​Duplicate table views across projects

​Share a dataset

​Next steps

Organize datasets

Tag and star datasets

Save snapshots

Define schemas

Edit datasets

Filter records

Update records

Delete records

Flush records

Review datasets

Configure review scores

Assign rows for review

Create custom dataset views

Customize table views

Create custom columns

Create custom table views

Set default table views

Duplicate table views across projects

Share a dataset

Next steps