The SQL editor
Autocomplete, multi-tab, cancellation, and addressable results.
Click Query in the sidebar to open the editor. You can also start from a dataset on Home:
double-click its node, right-click it and choose Query, or press Open in Query on its Data preview
tab. Each of these puts a SELECT * on that dataset into a tab, ready to run.
The SQL is DataFusion with the PostgreSQL dialect. DataFusion SQL lists what differs from PostgreSQL.
Tabs
Each tab holds one query and its latest result. A tab is named after the first non-blank line of
its SQL, so a leading -- comment makes a good title; an empty tab reads Untitled. Press + to open
a tab and the × on a tab to close it. Closing the last tab leaves an empty one.
Tabs are saved in your browser for the tenant, and they are there when you come back. They do not follow you to another browser or device.
Write the query
Autocomplete knows your datasets' real schemas. It suggests table names and their columns with each column's type, so you rarely need to look a name up. If you do, the Tables button in the page header lists every dataset, and clicking one copies its name.
The buttons in the editor's bottom corner format the SQL, switch between a compact and a tall editor, and open a menu with the shortcuts and a link to the DataFusion SQL reference.
| Action | Shortcut |
|---|---|
| Run the query | Cmd+Enter or Ctrl+Enter |
| Format the SQL | Shift+Alt+F |
| Show suggestions | Ctrl+Space |
| Accept a suggestion | Tab |
Run and cancel
Press Execute in the editor footer or use Cmd/Ctrl+Enter. While the query runs, the button reads Running…, the editor is locked, and a Cancel button appears beside it. Errors appear above the editor.
Cancel stops the page waiting for the answer. The query itself keeps running, and if it succeeds its result shows up under Recent results. Switching tabs, opening a new tab or picking a recent result while a query runs has the same effect. A query can run for up to 30 minutes.
Read the result
The result header shows the stored row count out of the total the query produced, and the run time. When a query returns more than 1,000 rows, Beetl keeps the first 1,000 and adds a preview label; the header then reads, for example, 1000 of 48210 rows. Export covers what to do when you need all of them.
The table loads more rows as you scroll, up to the stored rows. Each column header shows its data
type, and missing values show as null. Wrap shows long values in full and Truncate cuts them back to
one line. Expand fills the screen with the table, and Close or Esc returns to the editor.
After a run the address bar shows the result's own URL. Reloading or bookmarking it brings the same result back in a tab without running the query again, for 7 days. Only you can open your results; see Query results.
From the header you can also switch to Chart (see Result charts) or download the rows with CSV. Click any cell to see the column's role, the expression behind it and the tables it reads, and to drill into the records behind the value. Lineage and drill-down explains what you get.
Recent results
The Recent button in the page header lists your 10 latest results from this editor that have not expired, each with its SQL, row count and time. Drill-downs and queries run by the Assistant, an MCP client or an automation are not listed there.
Picking one opens it in the current tab. The editor keeps whatever SQL the tab already had, so open a new tab first if you want the result and its SQL side by side.
Links that open the editor
You can open the editor from a link:
| Link | What it opens |
|---|---|
/web/query?sql=<SQL> | The URL-encoded SQL in a new tab, or the tab that already holds exactly that SQL. It does not run until you press Execute. |
/web/query-results/<result_id> | That result. It loads into the current tab if the tab has no result yet, otherwise into a new tab. /web/query?result=<result_id> does the same. |
To pass a query to a colleague, send a ?sql= link and let them run it. A result link opens only
for the person who ran the query.
Ask the Assistant
The Assistant sidebar works alongside the editor. Open it with Open Assistant at the right edge of the window. On the Query page it can read the SQL in your tabs, so you can ask it to write a query, explain one, or fix the error you just got.
When it writes or changes SQL, it places it straight into the editor and the changed tab flashes briefly. It may run a query of its own to check its work, but nothing runs in your tab until you press Execute. Read the SQL before you do.
Related
Last updated on