> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# bt sql

> Run SQL queries against Braintrust from your terminal

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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
bt sql                                                          # Interactive terminal UI editor
bt sql "SELECT * FROM project_logs('my-project') LIMIT 10"      # Inline query
cat query.sql | bt sql                                          # Pipe from file
bt sql --non-interactive "SELECT count(*) FROM project_logs('my-project')"
```

## 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 (`project_logs(...)`, `experiment(...)`, `dataset(...)`)
* 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](/reference/sql/best-practices).