Query Variables
Last updated August 1, 2026 · By the SaturnSQL team
A variable turns a saved query into a form. Write the query once with a fill-in-the-blank placeholder, and from then on you change the answer instead of the SQL.
Write a variable
Type a {{name}} placeholder anywhere in your SQL:
SELECT customer, total
FROM orders
WHERE created_at >= '{{start_date}}'
AND created_at < '{{end_date}}'An input appears above the editor for each one, in the order they appear in the query. The ⚙ button beside an input sets its type, default and whether it is required. Names can use letters, numbers and underscores, and must start with a letter or underscore.
You write the quotes
The bare value is substituted where the placeholder sits, so quote dates and text yourself and leave numbers unquoted. It also means a query pasted from PopSQL runs unchanged.
WHERE region = '{{region}}'
ORDER BY total DESC
LIMIT {{row_limit}}Keep text variables inside quotes. Text is escaped so it cannot break out of the string literal you put it in. If the value belongs outside quotes, use a number, boolean or dropdown variable instead.
Types
- Date — a date picker, sent as
YYYY-MM-DD. - Text — anything, escaped for your database engine.
- Number — digits, with an optional sign and decimal point.
- Boolean — a checkbox, substituted as
trueorfalse. - Dropdown — a list of options you type one per line.
A new variable is guessed from its name: one ending in _date or _at becomes a date, anything else becomes text.
Defaults
A default fills the box when no value is supplied. For a date it can move: today, 7 / 30 / 90 days ago, start of last month, and so on, resolved when the query runs. Mark a variable Required and nothing runs until it is filled in.
An optional variable left blank substitutes nothing at all. That is useful for an open-ended range with NULLIF('{{end_date}}', ''), but it will leave a number or boolean stranded, so give those a default.
Schedules and reports
Nobody is present when a schedule fires, so a scheduled run uses every default, resolved in the schedule's timezone. Set start_date to 30 days ago and end_date to today and a fixed query becomes a rolling 30-day report. A required variable with no default fails the run, so give every variable a default before scheduling it.
You can also hand the query to someone who does not write SQL. Right-click a shared query and pick Show as report to get a page with just the inputs and the results table, and a Share button that copies a link to it.
Coming from PopSQL
Imported queries keep their {{variables}}, read straight out of the SQL. Two differences: names cannot start with a digit, so rename {{1_start_date}} to {{start_date}} (SaturnSQL orders inputs by where they appear in the query, so the number prefixes are not needed); and templating such as {% if %} is not supported, so use the NULLIF pattern above instead. Full walkthrough: migrating from PopSQL.
From the API
POST /api/queries/{id}/run runs a saved query from values, with an API key carrying the execute scope. You send values, never SQL, and every one is checked by type and escaped on the server.
curl -X POST https://saturnsql.com/api/queries/clx123/run \
-H "Authorization: Bearer sat_live_..." \
-H "Content-Type: application/json" \
-d '{"values": {"start_date": "2026-07-01"}}'An invalid value comes back as 422 with one entry per offending variable, and nothing is executed. See the API reference for the full schema.