SQL editor

The SQL editor is where you query a data source directly in SQL. It only reads: each run is a single SELECT or WITH statement, checked before it reaches your database. A query worth keeping is saved to the saved-query library, where dashboards, reports, stories, presentations and metrics can use it.

Prefer not to write SQL? The visual query builder makes the same saved queries from a chain of steps.

Start from a real table

Open SQL in the sidebar and choose New SQL query. A new tab opens on the first real table of the selected source, so there is always something to run.

1. Open SQL. The toolbar's Data source decides what the schema browser on the left shows, and the browser opens the source and its schema for you. The new tab already holds a query on the first real table.

   

2. Choose another Data source and the starter query moves with it: the tab you have not typed in is re-seeded with a query on the first table of the new source. Your own text is never replaced.

   

3. Choose Run (the play button). The rows appear under the editor.

   

4. Running an empty tab does not fail silently. It tells you to write a query, or to press the play button beside a table on the left.

   

Write and run a query

• Run (Ctrl+Enter, ⌘+Enter on macOS) runs the tab’s statement on the tab’s source. Cancel stops a run that is taking too long.
• Format (Ctrl+Shift+F, ⌘+Shift+F on macOS) lays the statement out clause by clause and capitalizes its keywords. A statement it can’t read is left as it is.
• The editor suggests SQL keywords as you type and wraps long lines.
• After a run, the bar under the editor says how many rows came back and how long it took (120 rows in 85ms).
• A run returns up to 1,000 rows. When the source has more, the bar adds capped — more rows exist. Narrow the query with a WHERE, an aggregate or a LIMIT of your own to see what you need.

Run a table with the play button

The play button beside a table in the schema browser writes SELECT * with LIMIT 100 for that table and runs it, in the current tab if you haven’t typed in it, otherwise in a new one.

1. In the schema browser, point at a table. A play button appears at the end of its row.

   

2. Choose the play button. The editor shows SELECT * with LIMIT 100 and the first 100 rows load underneath. A tab you have not typed in is reused, so your own work is never overwritten.

   

3. Open a table to list its columns and their types. Choose a column to insert its name into the query at the cursor.

   

Tabs and drafts

• Tabs: New tab opens another query (Query 1, Query 2, …). Each tab keeps its own SQL and its own data source, so switching tabs brings back both.
• Unsaved changes: a tab with changes not yet saved shows a dot (•). Closing it asks Discard unsaved changes? first, and leaving the editor asks Leave SQL editor?, saying how many tabs would lose their changes; Stay keeps you where you are.
• Draft recovery: your open tabs are kept in this browser for up to 7 days. If the browser closes or crashes, the editor brings them back with a notice: Autosaved in this browser for up to 7 days, and when. Drafts belong to you and the workspace, in this browser only: another browser or computer doesn’t see them, and a private window keeps none.
• Links to a query: /sql/new?q=<id> opens a saved query in a tab of its own, and &run=1 runs it too. A tab you were working in is kept: Your in-progress query was preserved; the saved query opened in a new tab.

The schema browser

The panel on the left lists source → schema → table → column, with each column’s data type.

• Insert a column name: click a table to open it and list its columns, then click a column (Insert into query) to put its name in the query at the cursor.
• Filter tables… narrows the tree to the tables whose name contains what you type, and an open table’s columns the same way.
• No schemas found: when a source has no schema read yet, Discover Schema reads it in the background (Discovering schema…) and says Schema discovery complete. when the tree is ready. After your database changes, use Sync on the source’s card to read its schema again (see Refreshing data & schemas).
• Collapse schema browser gives the editor the full width; Expand schema browser brings it back. With no data source connected, the panel says Connect a data source to browse schemas.

SQL compatibility and safety errors

Write SQL for the source selected in the tab. PostgreSQL-family sources such as Neon, Supabase, AlloyDB and managed PostgreSQL services accept PostgreSQL syntax in safety validation, including ::numeric casts and ILIKE. Azure SQL uses SQL Server syntax such as TOP. Warehouse-managed datasets use the same validation grammar as ClickHouse sources.

Execution requires a single read-only statement that DataSquares can parse. If you see Query could not be parsed for safety verification, check the selected source and simplify any vendor-specific syntax. A database can support syntax that the safety parser does not yet understand, such as a query hint (OPTION (…)) or WITH XMLNAMESPACES on SQL Server, Azure SQL and Azure Synapse; such statements remain blocked. Passing this check does not bypass source permissions, row-level security or restrictions on sensitive columns. On SQL Server and Azure SQL a temporal table can be read with any FOR SYSTEM_TIME clause: AS OF, FROM … TO, BETWEEN … AND, CONTAINED IN or ALL.

SQL Server, Azure SQL and Azure Synapse run a second statement that follows a query without a semicolon, so a reserved word that starts a statement, written after a query (such as CHECKPOINT after its table), is refused as Multiple SQL statements detected, with the word. To use such a word as a name, write it in brackets: [CHECKPOINT].

A query in parentheses can start a second statement too. Written right after a value or a name, as in WHERE b = 'x' (SELECT …), it is not part of the query before it, so it is refused the same way, naming what it follows. To use it as a subquery, put an operator or a keyword such as = or IN before it. To pass it to a function, put it in parentheses of its own: ISNULL((SELECT …), 0).

A block comment that holds another /* is refused on every source, with the reason “a block comment holds another /*”. Some databases, such as SQL Server and PostgreSQL, nest block comments, while others, such as MySQL, end one at its first */, so such a comment could hide what follows it. Remove the inner /*.

The row limit sorts a UNION, EXCEPT or INTERSECT from outside it on Azure Synapse dedicated SQL pools, which take no OFFSET, and on SQL Server and Azure SQL when a branch not in parentheses has its own TOP. There only the result’s own column names and positions can be read, so an ORDER BY that names a column with its table, such as ORDER BY t.a, is refused before it runs, saying so. The message names the item to change by its place in the ORDER BY, such as the 2nd item, and never quotes the query: the message of a saved query also reaches the people who view its dashboard or a shared link, who are not shown its SQL. Write that column’s name alone (ORDER BY a, or the alias the first query gives that column), or its position, such as ORDER BY 1.

Results, visualization, and export

Under the editor, three tabs show what a run returned:

• Results: the rows in a paged table, 20 a page to start (50 or 100 to choose), with the row count beside the tabs.
• Visualize: a quick bar chart for a first look, before you build a dashboard: up to five numeric columns over the first 50 rows, each bar named by the first text column (or by row number when there is none). A result with no numeric column says No numeric columns found to visualize. To chart a query properly, save it and add it to a dashboard.
• Saved: your saved queries. Filter saved queries…, then run one, load it into the editor or copy its SQL; Manage opens the library.

CSV, beside the tabs, downloads the rows the run returned. A result capped at 1,000 rows exports those rows, not the whole table.

1. Write a query and choose Run. The Results tab shows the rows with a count; longer results are paged.

   

2. Open the Visualize tab to chart the result. The first text column becomes the categories and the numeric columns become the values.

   

3. Back on Results, CSV downloads the rows. Use the toolbar to Format the SQL, or copy it to share.

   

4. New tab opens another query next to this one. A dot on a tab means it has changes you have not saved.

   

Every column, every digit

Two result columns with the same name both appear — the second as name_2 (the next as name_3) — and a column the database leaves unnamed (SQL Server’s SELECT 1, 2) shows as column_<n>, its position. Databricks, Dremio, Drill and Tinybird return rows keyed by column name, so there such a query is refused with a request to alias the column. A number too long for a floating-point double (a 20-digit id, a 38-digit decimal) is shown as its exact digits instead of a rounded value. SQL Server DECIMAL, NUMERIC and MONEY values in query results are still rounded past 15 digits. Databricks refuses what would arrive rounded instead: in a result the warehouse sends in its column-based format rather than Arrow, a DECIMAL above 15 digits, a BIGINT of 2^53 or more and every ARRAY, MAP and STRUCT column, and in any result an ARRAY, MAP or STRUCT column sent as JSON text. Cast the column to STRING in the query or the model to read it exactly.

AI assistance

• Explain describes the current tab’s SQL in plain English, in a panel in the editor.
• AI Generate opens a box: Describe the query you want in plain English…, then Generate (or Enter). The answer appears as AI-generated SQL: Accept puts it in the current tab in place of what is there, Reject drops it. Generate is not told which source the tab runs on, so name the tables and columns you mean, and read the SQL before you run it: it meets the same safety check as any other.
• When the AI can’t answer, the editor says why, such as AI credits used up, Monthly AI budget reached, AI is turned off here or AI is temporarily unavailable.
• AI credits: each Explain and each Generate is answered by the AI and uses AI credits, as the toolbar says. Run, Format, Save and Saved use no AI.
• Report: Report this answer (on an explanation) and Report this SQL (on generated SQL) report an answer that is offensive, harmful or wrong: choose a Reason, add a note if you like, and Send report, as in AI chat.

Save a query

Save opens Save Query: a Query name and an optional Description. The query is saved with the tab’s source and joins the saved-query library.

• Saving is checked like running: a statement Run would refuse for the source is not saved, and the error says why. Moving a saved query to another source checks its SQL in that source’s syntax.
• Update or save as new: in a tab opened from the library, the dialog offers Update “…” (with the query’s name, cut to 20 characters, such as Update “Monthly revenue”), which writes the tab’s SQL and source into the existing query, and Save as new, which leaves the original as it was. An update reaches everything that reads the query: its dashboard cards, report blocks, story numbers, slides and metrics read the new SQL from then on.

Saving over a visually-built query clears its steps

Queries built in the visual query builder keep their steps alongside their SQL. If you edit one of them here and update it, the steps are discarded for good: the query becomes SQL-only and can no longer be opened on the canvas. To keep the visual version, Duplicate it in the library first and edit the copy.

Who can use it, and what it refuses

The SQL editor follows the permissions of the SQL menu on the Roles screen: View to open the editor, run queries and browse the library, Create to save a new query, Update to update one in place or change its tags, Delete to delete one. An API key runs SQL only with the query:execute scope. The built-in roles have:

Built-in role	View	Create	Update	Delete
Admin	✓	✓	✓	✓
Editor	✓	✓	—	—
Viewer	—	—	—	—

So an Editor writes, runs and saves new queries, but can’t update a saved query in place: Update “…” is refused, and Save as new is the way to keep a change. A custom role can be given any of the four.

SQL here reads tables directly, past the data models where row-level security is applied, so:

• Row-level security: when a row-level security policy applies to you on a data source, the editor refuses to run SQL against it (Row-level-security policies apply to your account for this data source, so raw SQL cannot be run against it.). If DataSquares can’t tell whether one applies, it refuses too. Read that data through a model, which applies your policy.
• Sensitive columns: a query that reads a column with a sensitivity label is refused to anyone whose role may not read it.

Related

• Saved queries
• Visual query builder: build the same thing without SQL.
• Connect your data
• Users and roles
• Keyboard shortcuts