bt sql

Run SQL queries against Braintrust. In a terminal, bt sql opens an interactive editor with query history. Pass a query directly or pipe from stdin for scripting.

bt sql "SELECT * FROM project_logs('project-name') WHERE created > now() - interval 1 day LIMIT 5"
bt sql -p project-name "SELECT * FROM logs WHERE created > now() - interval 1 day LIMIT 5"
cat query.sql | bt sql
bt sql --non-interactive "SELECT count(*) FROM project_logs('project-name') WHERE created > now() - interval 1 day"

Most SQL data-source functions also accept an object name in place of its ID. See Querying by name.

When a project is selected through bt switch, --project, or BRAINTRUST_DEFAULT_PROJECT, use FROM logs as shorthand for that project’s logs. bt resolves the project and replaces the shorthand with project_logs('<project-id>') before sending the query. Use project_logs('<project-name-or-id>') when the query should name a project directly instead of using the selected context.

Interactive controls

Key	Action
`↑` / `↓`	Navigate query history
`Enter`	Execute query
`Ctrl+c`	Clear input
`Ctrl+l`	Clear output
`Ctrl+d` / `Esc`	Exit

Query syntax

A FROM clause is required (logs, project_logs(...), experiment(...), or dataset(...))
FROM logs requires a selected project
Prefer filtering with WHERE; use HAVING only after aggregation
Joins, subqueries, unions, and window functions are not supported
Use explicit column aliases and type casts for clarity
Paginate large results with OFFSET '<cursor_token>'

For tips on query performance and common pitfalls, see SQL best practices.

Flags

Flag	Env var	Description
`--non-interactive`	—	Force non-interactive mode
`--force-ignore-linter`	`BRAINTRUST_SQL_FORCE_IGNORE_LINTER`	Run the query even when the SQL linter reports failures

API

CLI

SQL

Interactive controls

Query syntax

Flags

​Interactive controls

​Query syntax

​Flags

Interactive controls

Query syntax

Flags