Skip to main content

SQL Workbench

The SQL Workbench is where you query analytics tables. It pairs a SQL editor that knows your tables, columns, and measures with a results grid that scrolls smoothly through hundreds of thousands of rows. Queries run asynchronously as background jobs, and typically take a few seconds. A long query keeps going if you navigate away, and you can come back to it from your history.

What it's for​

  • Exploring a new dataset and checking that a load landed correctly.
  • Answering one-off questions that are easier to write as SQL than to build a report for.
  • Writing and checking the verified queries that agents rely on.
  • Exporting a result to CSV or Parquet.
  • AutessaDB → SQL Workbench opens the workbench with every analytics table you can read in the schema sidebar, for queries that join several tables.
  • Open workbench on an analytics table's detail page opens it focused on that table.

Key concepts​

Layout​

  • Schema sidebar on the left: your analytics tables, each expanding to its columns (with types) and measures. Click a name to insert it at the cursor.
  • Editor in the center: SQL highlighting and completion for table names, column names, and measures.
  • Run controls above the results: Run, Run selection, Estimate, Cancel, and a row limit.
  • Results below: a grid with a sticky header, resizable columns, and horizontal scrolling for wide results.
  • History opens as a drawer on the right.

What SQL you can write​

Each run is one read-only statement: a SELECT, optionally with WITH common table expressions, UNION, joins, subqueries, and window functions. The dialect is ANSI SQL: standard SQL works as written, and analytical functions follow the common names, for example date_trunc('month', order_date) to group by month, approx_distinct(customer_id) for a fast distinct count, and format_datetime(order_ts, 'yyyy-MM') to format a timestamp. Date literals are written DATE '2026-01-01'. Statements that change data or settings are rejected before they run. Refer to tables by their SQL names; tables you cannot read are reported as unknown.

Estimates​

Estimate reports roughly how much data a query would scan (for example, "Scans ~1.2 GB") without running it. The workbench also refreshes the estimate shortly after you stop typing. Use it to catch a missing partition filter before you run an expensive query.

Results​

The grid shows typed values: decimals and very large integers exactly as stored, timestamps in your local time with UTC on hover, and empty values as a muted null. The toolbar shows the row count and run time, and offers Download CSV, Download Parquet, Copy, and Save as verified query.

The row limit caps how many rows come back. If a result was cut off, the toolbar says so; add filters or aggregation, or raise the limit.

Drafts and history​

Your unsaved SQL is kept as a draft for each table in this browser. History lists your recent runs with their status, run time, and rows; click one to reopen its SQL and result. Results are kept for 7 days.

How to run a query​

  1. Open the workbench.

  2. Write a query, for example:

    SELECT region, date_trunc('month', order_date) AS month, SUM(net_amount) AS revenue
    FROM order_lines
    WHERE order_date >= DATE '2026-01-01'
    GROUP BY 1, 2
    ORDER BY 2, 1

  3. Press Ctrl+Enter (Cmd+Enter on Mac) or click Run. To run only part of the editor, select it and press Ctrl+Shift+Enter or click Run selection.

  4. Results appear in the grid as soon as the job finishes, typically within a few seconds. While it runs you can click Cancel, or leave the page and come back to it from History.

How to check a query's cost​

  1. Write the query and watch the estimate next to the run controls, or click Estimate.
  2. If the estimate is large, add a filter on a partition column (shown in the schema sidebar) or narrow the columns you select.

How to download results​

  1. Run the query.
  2. Click Download CSV or Download Parquet in the results toolbar. The download contains the full result up to the row limit, not only the rows on screen.

How to save a verified query​

  1. Run the query and check the result.
  2. Click Save as verified query, and write the question it answers in plain language ("Monthly revenue by region this year").
  3. The query appears in the table's semantic layer, where agents can find and reuse it.

How to ask in plain language​

  1. Click Ask and describe what you want to know.
  2. The assistant proposes SQL and inserts it into the editor. Nothing runs until you click Run.