Dashboard variables

A dashboard’s variables filter every widget at once. Each one shows as a control in the bar under the dashboard’s filters. Its value goes into any widget SQL that names it as $name.

Add variables

Open a dashboard and click Variables in the bar (you need permission to update dashboards). For each variable, set:

Field	What it does
Name	How widget SQL refers to it: service is $service. Lower-case letters, digits and underscores, up to 32 characters.
Label	What the bar shows.
Values from	Where its values come from (see below).
Several values	Lets people pick more than one value.
Offer All	Adds All, meaning every value.

A dashboard has up to 10 variables. They are saved with the dashboard and kept when you export and import it.

Where values come from

Kind	Values
Services	Every service.name in the last 7 days of traces
AI models	Every gen_ai.request.model in the last day of traces
Environments	Every deployment.environment in the last day of traces
Hosts	Every host (host.name, or the Kubernetes node) in the last day of host metrics
A query	The first column of a read-only SELECT you write. It can use the dashboard’s filters ({{filter.timeLimit.start}}), but not other variables.
A list I type	The values you list, one per line

Each variable lists at most 200 values. The lists are read for the project and environment you are in, and kept for a minute.

Use them in widget SQL

Write $name (or ${name}) where the value goes:

SELECT toStartOfHour(Timestamp) AS hour, count() AS requests
FROM otel_traces
WHERE ServiceName = $service
  AND Timestamp >= parseDateTimeBestEffort('{{filter.timeLimit.start}}')
GROUP BY hour
ORDER BY hour

A variable that takes several values or offers All is a list. Compare it with IN:

WHERE ServiceName IN $service
  AND SpanAttributes['gen_ai.request.model'] IN $model

All, or nothing picked, is every value on the variable’s list. A single-value variable with nothing picked uses its first value.

Share a filtered dashboard

The values you pick are kept in the page address, for example ?var-service=checkout&var-model=gpt-4o. Send the link and the dashboard opens with the same values.

How values are kept safe

• Values are never pasted into SQL. Each $name becomes a ClickHouse query parameter.
• The server works out each variable’s values itself and uses only the picked values that are on that list. A value typed into the address that is not on the list is ignored.
• A variable’s query must be a single read-only SELECT. It runs with the same limits as widget queries.