Templating with variables

A static SQL query becomes a flexible dataset when you add templates — placeholders that get filled in at query time by dashboard controls or chart filters.

Variables: {{name}}

Wrap any variable name in double curly braces. trend substitutes its value at query time.

SELECT count(*) FROM orders
WHERE region = {{region}}

When a dashboard control sets region to 'US-East', the query runs with that bound as a parameter (not string-interpolated — we always use prepared statements).

Optional clauses: [[...]]

Wrap an entire clause in double square brackets to make it conditional. If the variable inside is missing or empty, the whole clause drops cleanly.

SELECT count(*) FROM orders
WHERE 1=1
  [[ AND region = {{region}} ]]
  [[ AND created_at >= {{start_date}} ]]

• If region is set: the AND clause is included.
• If region is empty: the AND clause is dropped entirely.

This is the cleanest way to write a dataset that supports multiple optional filters — no WHERE region = COALESCE({{region}}, region) gymnastics needed.

Dot-paths for compound variables

Some variables are compound — a date range has startDate and endDate for example. Reference them with a dot:

WHERE created_at BETWEEN {{my_range.startDate}} AND {{my_range.endDate}}

The dashboard’s date-range control auto-creates the my_range variable with both sub-fields.

What to read next

• Controls and variables — how the dashboard side wires up to these templates.