SQL Editor
Write and run SQL queries directly against your project's traces, observations, scores, sessions, dataset runs, and experiment runs — and save aggregated results as dashboard widgets.
SQL Editor
The SQL Editor lets you query your project's data using raw SQL, view the results as a table or chart, and save aggregated queries as dashboard widgets.
Getting Started
- From the Dashboards page, click SQL in the top-right to open the SQL Editor.
- Write a
SELECTstatement (or pick a recent one from History), then click Run. Up to 1,000 rows appear in the results panel below. - If the query is aggregated — it has a
GROUP BYor an aggregate likeCOUNT,SUM, orAVG— click Save to Dashboard to turn the result into a widget on any of your dashboards.
The rest of this page covers each step in detail.
Available Tables
The editor exposes two groups of tables. Each table is scoped to your current project — you cannot access another project's data.
Observability tables
These hold your live trace data. Queries against them default to the last 7 days unless you add your own time filter.
| Table | What it contains |
|---|---|
traces | One row per trace (LLM request or operation) |
observations | One row per span, generation, or event within a trace |
scores | Evaluation scores attached to traces |
sessions | Aggregated view of traces grouped by session_id |
Key time columns (use these when adding a time filter):
| Table | Primary time column |
|---|---|
traces | timestamp |
observations | start_time |
scores | timestamp |
Evaluation and experiment tables
These hold your dataset and experiment metadata. No automatic time filter is applied.
| Table | What it contains |
|---|---|
dataset_runs | Runs of a dataset against an experiment |
experiment_runs | Individual experiment execution records |
dataset_items | Items within a dataset |
You can't JOIN tables across the two groups (for example, traces with dataset_runs). Write a separate query for each group.
Running a Query
Write your SQL
Type a SELECT statement in the editor. The editor provides syntax highlighting and autocomplete for table and column names based on the live schema.
Start simple — count the traces in your project:
SELECT count(*) AS total FROM tracesGroup and aggregate to get something chart-worthy (this shape can be saved as a dashboard widget):
SELECT
name,
count() AS trace_count
FROM traces
GROUP BY name
ORDER BY trace_count DESC
LIMIT 20Aggregate cost by model from the observations table:
SELECT
provided_model_name AS model,
sum(total_cost) AS total_cost_usd,
count() AS generations
FROM observations
GROUP BY model
ORDER BY total_cost_usd DESC
LIMIT 20These examples have no time filter, so they use the automatic 7-day window. To widen or narrow it, add your own filter on the table's time column — for example WHERE timestamp >= now() - INTERVAL 30 DAY on traces.
Run the query
Click Run.
While the query is executing, a Cancel button appears. Click it to abort the in-flight query and return the editor to a runnable state.
Inspect the results
The results panel shows up to 1,000 rows. A notice appears if your result was truncated.
- Table view — browse rows and columns directly.
- Chart view — for aggregation-shaped queries the editor suggests a chart type. Use the chart-type dropdown to switch between bar, line, pie, and other visualizations.
Schema Panel
The schema panel on the left lists every table and its queryable columns, grouped by the two table groups above. Click any column name to insert it at the cursor in the editor.
The schema refreshes from the live catalog every 15 minutes, so newly added columns appear automatically without a page reload.
Tabs and Query History
Tabs
The editor supports multiple tabs so you can work on several queries at once. Use the + button in the tab bar to open a new tab. Click the tab name to rename it. Tabs persist across page reloads within the same project.
Query History
The History section at the bottom of the schema panel lists your recent queries along with execution time and row count. Click any entry to load it back into the active tab.
Saving a Query as a Dashboard Widget
Aggregation-shaped queries (those with a GROUP BY or aggregate function) can be saved as widgets on any of your project's dashboards.
Check that the query is savable
After running the query, the Save to Dashboard button is enabled when the result is chartable. If it remains disabled, hover over it to see why (e.g. "Add a GROUP BY or aggregate function").
Open the save dialog
Click Save to Dashboard. A dialog opens with a live chart preview using the auto-detected (or user-selected) chart type.
Choose a dashboard and widget name
Select an existing dashboard (or create a new one) and give the widget a name. Choose the final chart type and click Save.
The saved widget is immediately available on the selected dashboard and can be added to other dashboards from the Add Widget dialog. See Widgets for the available chart types and Custom Dashboards for arranging them.
Exporting Results to CSV
After running a query, click Export CSV in the results panel to download the full result as a CSV file. The export re-runs the query server-side without the 1,000-row display cap, so the file contains every matching row.
The export applies the same safety checks and project-isolation rules as the interactive query. The download begins in a few seconds; keep the page open while it prepares.
Query Safety and Limits
The SQL Editor enforces the following restrictions to protect data integrity and performance:
| Rule | Detail |
|---|---|
| SELECT only | INSERT, UPDATE, DELETE, DROP, CREATE, and other DDL/DML statements are rejected. |
| Single statement | Only one statement per query is allowed. CTEs (WITH …) count as a single statement. |
| Table allowlist | Only the tables listed above are accessible. Queries referencing system tables (information_schema, system.*) are rejected. |
| Row cap | Interactive results are capped at 1,000 rows. CSV export is uncapped. |
| Scan guard | Queries projected to scan too much data return an error with guidance to add a WHERE filter, a narrower time range, or an aggregate. |
| Default time window | When no time filter is present, queries against traces, observations, and scores are automatically scoped to the last 7 days. |
| Function restrictions | Certain functions that could expose system internals or allow remote calls are blocked (e.g. cluster(), remote(), pg_read_file, dblink_*). |
Required Permissions
| Action | Required Role |
|---|---|
| Run SQL queries | All project members |
| Save a query as a widget | Owner or Admin (dashboards:CUD) |
| Export CSV | All project members |
Related
- Widgets — the chart types a saved SQL query can render as
- Custom Dashboards — create and arrange dashboards to hold your saved queries
- Metrics — the built-in metrics and dimensions available without writing SQL