Manage datasets

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 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 }),
});

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

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

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,
  },
});

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

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.

Delete records

Remove records programmatically 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();

To delete an entire dataset, use the UI or the API.

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

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 two 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.
Personal default: Overrides the organization default 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 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 or Clear organization default view.

When a user opens a page, Braintrust loads the first match in this order: personal default, organization default, then the standard “All …” view (e.g., “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>'
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>
  }'

Next steps

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

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

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

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Documentation Index

​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

​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

Next steps