Documentation → How-to guides

Using the SQL Workbench

The Workbench is one tabbed workspace where you write spatial SQL, preview the rows it returns, and — when a query is worth keeping — turn it into a mappable dataset. This page is about driving the tool. For the SQL itself — the dialect, the geometry column, joins across sources — see Query and model data with SQL.

The layout

Open SQL Workbench from the sidebar. Each open model is a tab across the top, and one tab fills the work area:

A toolbar — the model's name, then Preview, the primary Run (or Save & Run) button, and a ⋯ menu for everything else.
An input chip row and the SQL editor below it, across the full width. Each input carries a short alias — the table name you write FROM — and + Add input opens the dataset picker.
A results dock beneath — the rows your query returned, with the result map beside them.

Preview, Run, Save — three actions, one decision

The whole loop is two buttons: check what your SQL returns, or commit to it. Everything else is configuration and lives under ⋯.

Action	What it does	Creates
Preview	Runs the SQL and shows the rows it returns. Reflects unsaved edits, so it is the inner loop you stay in while writing a query.	nothing
Run (a new model)	Names the output and materializes it. You are asked for a name and a layer ID once, here — the layer ID is written into the tiles and is permanent afterwards.	a new, tiled dataset
Save & Run (a saved model)	Stores the SQL change and re-tiles the output. The dataset keeps its id, so styling, map memberships and published links all survive.	replaces the output
Save (in ⋯)	Stores an SQL edit to a saved model without re-tiling — for when you are not ready to spend a tiling job yet.	nothing new

A draft has no name until you Run it — you can write and Preview a query you may never keep. The tab is titled New model until then; double-click the tab to name it early, or let the Run dialog ask.

Keyboard shortcuts

The keys follow the convention every SQL console uses — the modifier escalates the commitment. Enter runs; adding Shift runs the heavier variant.

Action	macOS	Windows / Linux
Preview — run the SQL, show rows	`⌘ Enter`	`Ctrl + Enter`
Run / Save & Run — materialize	`⌘ ⇧ Enter`	`Ctrl + Shift + Enter`
Save — store an SQL edit	`⌘ S`	`Ctrl + S`

The shortcuts act on the tab you are looking at, from anywhere in the editor. On a new model, ⌘ ⇧ Enter opens the Run dialog — the same one the button opens — so you still name the output before anything is created.

Preview versus Last run

The rows dock has two tabs once a model has run, and they answer different questions:

Preview is a live query of the SQL in the editor right now. It reflects edits you have not run.
Last run is the rows the materialized dataset actually holds — what your maps are reading. A failed run shows its error and job log here.

They diverge exactly when it matters: an edit you have previewed but not run, a run that failed, or a run that succeeded on older SQL. A brand-new model has only Preview, because there is no run to compare against yet.

Tabs and drafts

Open as many models as you like; each is a tab. Two things worth knowing:

Unsaved SQL is kept — for a draft and for an edit to a saved model alike. It survives a reload and a project switch, per project. The • on a tab means it holds work you have not saved.
Only the tab you are looking at renders its map. The others keep all their editor state but hold no live map, which is what lets you keep a dozen tabs open without the browser evicting them.

The result map

The result map renders only after a successful run — it shows the tiled output, styled as that dataset is styled. From the ⋯ menu you can put it beside the results (the default — it costs height, which is cheap), beside the editor (the old right-hand split, for real visual checking), or hidden. While a run is in flight the map keeps showing the previous result until the new one finishes.