Visual query builder

Visual query is a step-by-step way to build analytical queries without writing SQL. You start from a data source table and stack steps on it — filtering, joining, grouping, sorting — and the results preview updates automatically as you build, alongside the exact SQL your steps compile to.

What comes out is a standard saved query that stores both the compiled SQL (CTE-per-step) and the visual DAG steps (builder_steps). It charts on dashboards anywhere a saved query does and reopens on the visual canvas whenever you need to modify it.

Open the builder

From the Queries page:

• New visual query (next to New SQL query) opens an empty visual canvas.
• An existing visually-built query reopens from its row menu → Open in visual builder (or deep link /query-builder?q=<queryId>).

Build a query

1. Pick a source and starting table. Select a data source, schema, table, and columns to initialize the first source step on the canvas.

2. Add transforms. Click + Step on the toolbar to append a transform to the terminal step of your chain. To combine tables, select Join another table or Union another table.

3. Configure step parameters. Click any node on the canvas to open its configuration inspector in the side panel.

4. Inspect live preview & SQL. Live preview refreshes automatically (debounced by 600ms), displaying the first 50 rows, row count, and any syntax or execution errors. Click SQL on the toolbar to inspect or copy the compiled SQL.

5. Save. Click Save to store the query with its compiled SQL and visual steps into the saved-query library, or choose Save & edit as SQL to transition directly into the SQL editor.

Canvas interactions

The visual canvas is powered by an interactive node graph:

• Auto-layout: Linear flows stack in a clear top-to-bottom vertical chain. Adding a join or union automatically branches into multi-lane lanes.
• Node dragging: Node dragging becomes available as soon as the pipeline branches into a multi-source graph.
• Node inspector: Clicking any node highlights it and opens its configuration panel on the right.
• Safe deletion: Steps cannot be deleted if downstream steps depend on them (“Remove downstream steps first”). Deleting a Join or Union automatically cleans up its private branch source.
• Terminal step: New transforms always append to the active graph terminal.

Step reference

Step	What it does	Configuration options
Source	Reads a table. Every query starts with one; joins and unions add another branch.	Data source, schema, table, columns
Filter rows	Filters rows matching one or more conditions.	Column, operator (eq, neq, gt, gte, lt, lte, like, is_null, is_not_null), value
Remove columns	Drops unnecessary columns downstream.	Checkbox multi-select of columns to drop
Rename column	Renames a single column.	Source column (from) → Target name (to)
Change type	Casts a column to another data type.	Column, target type (string, integer, decimal, date, datetime, boolean)
Add column	Adds a computed column evaluated via a SQL expression.	Column name, SQL expression (e.g. amount * 1.2 or coalesce(discount, 0))
Replace values	Replaces matching values within a column.	Target column, list of find → replace pairs
Sort rows	Orders rows by a column.	Column, direction (ascending, descending)
Keep top N	Limits output to the first N rows.	Row count (default 100)
Deduplicate	Retains only unique rows based on selected key columns.	Key columns (keeps the first occurrence per key)
Group & aggregate	Aggregates rows into grouped summaries.	Group-by columns, aggregations (count, sum, avg, min, max) with column and output alias
Join	Combines two tables side-by-side on join keys.	Join type (left, inner), left key, right key, right columns to bring across
Union	Stacks rows from another table underneath.	Distinct rows toggle (UNION vs UNION ALL) across shared columns

Joins and unions

Join another table and Union another table create a new branch source node alongside the join/union node:

• Join: Select left or inner join. Choose the left key from available input columns, enter the right key name, and select which right columns to include. If a right column name collides with a left column, it is automatically prefixed with right_ (e.g., right_amount).
• Union: Select whether to enforce distinct rows (UNION) or keep all rows (UNION ALL). Only columns present in both tables are preserved in the left table’s column order.

Note

Both tables must reside on the same data source. Cross-source visual joins are handled at the data model level or via pipeline flowlets.

Live preview and compiled SQL

• Debounced execution: Previews update within 600ms after edits stop, executing against your data source for real-time validation.
• Compiled SQL modal: Click SQL to open the compiled SQL viewer. Each step compiles into an individual Common Table Expression (CTE), concluding with a SELECT from the final step.
• Copy SQL: Copy the full compiled query to clipboard with one click.

Transitioning to the SQL editor

Hand-editing SQL permanently clears visual steps

A visual query retains its step DAG alongside compiled SQL. If you open a visually-built query in the SQL editor and modify its SQL by hand, the visual steps are permanently discarded. The query becomes SQL-only and can no longer be reopened on the visual builder canvas.

• Save & edit as SQL: When you need advanced SQL features (window functions, custom CTEs, complex case statements), use Save & edit as SQL to save the query and seamlessly open it in the SQL editor.
• Preserve visual originals: To experiment with raw SQL without losing the visual version, duplicate the query from the Saved Queries library before hand-editing.

Limits and governance

• 60 steps maximum per visual query graph.
• One data source per query: All branch source steps in a visual query must connect to the same data source.
• Plain identifiers: Column and table names must consist of alphanumeric characters and underscores.
• Row-level security: If RLS policies apply to a data source, visual raw table preview is blocked to maintain security boundaries. Use Data models or the SQL editor instead.

Related

• Saved queries — library management, tags, and dashboard usage.
• SQL editor — raw SQL workspace with Monaco editor, formatting, and AI.
• Data models — relational model canvas and semantic modeling.
• Keyboard shortcuts