Variables and time range

Add placeholders to a query so viewers can pick dates or values, and give a report its own time range.

You will make a query reusable with placeholders and let report viewers change the date range.

Before you start: you need access to the Query workspace. Setting a report's default range needs Full control.

Write a variable

Put {{name}} in your SQL, or {{name=default}} to give it a default.

SELECT status, COUNT(*) AS invoices
FROM invoices
WHERE status = '{{status=overdue}}'
GROUP BY status
  • Names start with a letter or _ and use letters, digits and _.
  • A plain number is used as a number; anything else becomes safe text. Both '{{x}}' inside quotes and bare {{x}} work.
  • A variable with no default and no value stops the run with an error naming it.
  • Values are limited to 256 characters, and a query may use up to 64 placeholders.

Fill variables in the workspace

When your SQL has variables, a Variables strip appears under the editor with one box per variable. A blank box uses the default, and a box with no default shows "required".

Reserved date range

The names {{range.start}} and {{range.end}} are special. They are filled by a time range picker instead of a text box.

SELECT COUNT(*) AS orders_placed
FROM orders
WHERE created_at >= '{{range.start=2026-01-01 00:00:00}}'
  AND created_at <= '{{range.end=2026-12-31 23:59:59}}'

The picker's Time range options are All time, Today, Last 7 days, Last 30 days, Last 90 days, Last 12 months and Custom… (which adds From date and To date). Dates snap to whole days in your time zone. All time sends no values, so your defaults apply.

Time range on a report

  1. Open a report whose widgets use the range variables. The Time range picker appears in the header. It only shows when some widget uses the range, or a range is already set.
  2. A viewer's choice is their own for that visit. It is not saved.
  3. In edit mode, changing the picker sets the report's default range, which is saved. Presets are stored as presets, so "Last 7 days" keeps rolling.
  4. Your home page report also opens with its default range.

Other variables on a widget

For variables other than the range pair, open Configure… on the widget. A Variables section lets you pin a value for that widget. The report's time range always wins over a pinned range value.

Tips

  • Use a default so the query runs by itself.
  • Open in Sheets keeps your current values by writing them into the query as defaults.