Bind a Variable to a Query

Once a variable is defined on a dashboard, each panel decides whether to reference it. Binding a variable to a query is what makes the variable's selection actually flow into that query.

How you bind — and how much control you have over the operator applied to the value — depends on the panel's query mode. Every variable type has a Query Builder mode and a PromQL mode below.

Bind a Filter Variable

Filter variables offer the same expressive power in both modes: the operator and matching values both come from the user's runtime selection.

In a Visual Query Builder Panel

In the query editor, a matching filter variable appears in the Filters row as a Bind $variable_name button. The variable is available but not yet applied, so the PromQL preview does not reference it.

Click the button to bind the variable. It then shows as an active filter chip in the Filters row, and the $variable_nameCopy reference is interpolated into the PromQL Preview.

The Services panel's form promotes a few attributes to their own sections instead of the generic Filters row. When you bind a filter variable that targets one of those attributes, the Bind $variable_name button appears in the matching section:

• Filter variables on service.nameCopy or service.namespaceCopy are bound in the Service section.
• Filter variables on dash0.operation.nameCopy are bound in the Operations section.

Filter variables on any other attribute still appear in the Filters row, as usual.

In a PromQL Query

Reference the variable directly by placing $variable_nameCopy inside the label matcher. It interpolates to the entire matcher — both operator and values come from the selection:

1
{otel_metric_name="dash0.spans", $service_name}

12
# BAD — filter variables interpolate the whole matcher, not just the value
{otel_metric_name="dash0.spans", service_name="$my_services"}

Bind a List Variable

Unlike a filter variable, a list variable is not pinned to an attribute at definition time. The attribute the variable filters on is chosen at bind time, in the panel.

In a Visual Query Builder Panel

A matching list variable appears in the Filters row as a Bind $variable_name button. Click it and pick the attribute key you want the variable's values to filter on. Once bound, the variable shows as a filter chip on that attribute, and the Query Builder writes the label matcher for you and always uses =~Copy. Single-value selections still work, because =~"a"Copy matches the same series as ="a"Copy.

In a PromQL Query

Type $variable_nameCopy in the label matcher yourself, choosing both the attribute key and the operator. The operator you write must match the selection method:

• Single-select: use an equality operator (=Copy), for example my_label="$variable_name"Copy.
• Multi-select: use a regex-match operator (=~Copy), for example my_label=~"$variable_name"Copy. The values are interpolated as a regex alternation like a|b|cCopy, which does not match with =Copy.

For a list variable $envCopy bound to service_namespaceCopy, a full single-select query looks like:

1
{otel_metric_name="dash0.spans", service_namespace="$env"}

At runtime, if the user picks stagingCopy, this becomes:

1
{otel_metric_name="dash0.spans", service_namespace="staging"}

A multi-select query on the same variable uses =~Copy:

1
{otel_metric_name="dash0.spans", service_namespace=~"$env"}

If the user picks both stagingCopy and productionCopy, the query becomes:

1
{otel_metric_name="dash0.spans", service_namespace=~"staging|production"}

Bind a Text Variable

Like a list variable, a text variable is not pinned to an attribute at definition time. You choose the attribute the value applies to when you bind it in the panel.

In a Visual Query Builder Panel

A matching text variable appears in the Filters row as a Bind $variable_name button. Click it and pick the attribute key the typed value should be matched against. The Query Builder writes the matcher for you and always uses =Copy — the typed value is matched literally, so any regex metacharacters the user types are treated as part of the value. A user who types checkout|paymentsCopy expecting either service will match nothing, because no series has a literal service.nameCopy of checkout|paymentsCopy.

In a PromQL Query

Type $variable_nameCopy where you want the value to appear, and pick the attribute key and operator yourself. Both operators work, and they change how the value is interpreted:

• =Copy (literal match): the value is matched as-is. Safer default when users are meant to type a plain string such as checkoutCopy or /api/v1Copy.
• =~Copy (regex match): the value is a Prometheus regex. Powerful (a user can type checkout|paymentsCopy to match either service), but any regex metacharacter (.Copy, *Copy, ?Copy, |Copy, (Copy, )Copy, [Copy, ]Copy, \Copy) is treated as regex syntax — a user who types 1.2.3Copy expecting a literal match will also match 1x2y3Copy.

For a text variable $versionCopy bound to app_versionCopy, a literal-match query looks like:

1
{otel_metric_name="dash0.spans", app_version="$version"}

If the user types 1.2.3Copy, this becomes:

1
{otel_metric_name="dash0.spans", app_version="1.2.3"}

which matches only the exact string 1.2.3Copy. Switching to =~Copy changes the semantics:

1
{otel_metric_name="dash0.spans", app_version=~"$version"}

Now the same input becomes:

1
{otel_metric_name="dash0.spans", app_version=~"1.2.3"}

which also matches 1x2y3Copy, 1a2b3Copy, and any other three-character-separator variant, because .Copy is a regex metacharacter meaning "any character."

Further Reading

• About Adding Variables — Understand the variable types and when to use each
• Build Queries — Write the PromQL that references your variables
• Use Filter Variables — Create attribute-based filters with automatic dependencies
• Use List Variables — Offer a fixed or query-driven list of selectable values
• Use Text Variables — Reuse a single text value across panels