> ## 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 "SELECT * FROM project_logs('<PROJECT_ID>') LIMIT 5"
cat query.sql | bt sql
bt sql --non-interactive "SELECT count(*) FROM project_logs('<PROJECT_ID>')"
```

<Tip>
  Most SQL data-source functions also accept an object name in place of its ID. See [Querying by name](/docs/reference/sql/query-structure#querying-by-name).
</Tip>

## 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](/docs/reference/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 |