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

# SQL

> Query your events directly in CarbonQL.

The SQL editor runs [CarbonQL](/documentation/dashboard/analytics) — Carbon's read-only SQL dialect — directly against your `events`. Open it from **SQL** in the dashboard.

## Write a query

Write a `SELECT` over the physical event columns. The schema panel on the right lists every column and allowed function; select one to insert it at the cursor.

```sql theme={null}
SELECT
  `properties:llm:model` AS model,
  count() AS calls,
  sum(`properties:llm:cost:totalUsd`) AS cost
FROM events
WHERE startTimeMs BETWEEN {fromMs:Int64} AND {toMs:Int64}
GROUP BY model
ORDER BY cost DESC
LIMIT 10
```

Select **Run** (or press <kbd>⌘</kbd><kbd>↵</kbd>) to execute. Results appear below the editor with the row count and query time.

## Scope and bounds

* `{fromMs}` and `{toMs}` are bound to the selected time range — reference them in your `WHERE` clause. Change the range from the header.
* Your query is automatically scoped to your space; you never write (and cannot widen) a `spaceId` filter.
* The editor is read-only by construction — the dialect cannot express writes or DDL — and every query runs under scan, memory, and row limits.

## Errors

A malformed query reports the failure inline, with the line and column when the engine can locate it, so you can jump straight to the problem.

<Note>Your draft is kept in your browser between visits. The editor does not save named queries.</Note>