Use dashboard variables

A dashboard variable groups a set of fields together so that viewers can switch which field a visualization displays. An author adds the variable to a visualization's encoding, such as the x-axis of a bar chart, and binds it to a control widget. When a viewer chooses a different field in the control, every visualization that uses the variable updates to show the selected field.

Dashboard variables let viewers answer their own questions through familiar point-and-click interactions, without editing the dashboard or waiting for a query to be regenerated. For example, a viewer can switch a line chart between Sales and Transactions, and the formatting updates accordingly.

Adding or removing multiple fields at once is not yet supported.

Choose between a dashboard variable and a parameter

Dashboard variables and parameters both make a dashboard interactive, but they operate at different layers. A dashboard variable changes which field a visualization displays at the dashboard layer. A parameter substitutes a value into a dataset query at runtime. For more about parameters, see Work with dashboard parameters.

Dashboard variables replace the previous approach of using the IDENTIFIER clause with a parameter to swap fields. Unlike IDENTIFIER, dashboard variables work with metric views and preserve the semantic formatting attached to each field.

Create a dashboard variable

You must have at least CAN EDIT permissions on the draft dashboard. You create a variable from a filter (control) widget:

1. On the draft dashboard canvas, click Add a filter (field/parameter) and place the filter widget on the page.
2. In the widget's configuration panel, create a variable and add the fields that you want viewers to choose between.
3. For each field, specify a transform and a display name:
   • The transform defines how the field is aggregated or bucketed (for example, SUM for a measure or DAILY for a date). The transform is defined as part of the variable and cannot be overridden where the variable is used.
   • The display name is the label shown to viewers in the control.

The first field in the variable is the default selection. The filter widget you used to create the variable becomes a control that viewers use to switch fields.

Field types and scale types

A variable can contain fields of different types. The scale type that a visualization uses depends on the field options in the variable:

• If all field options are numeric, the default scale type is quantitative. You can switch the encoding's scale type to categorical in the visualization editor.
• If all field options are date or datetime fields, the default scale type is temporal. You can switch the encoding's scale type to categorical in the visualization editor.
• Otherwise (for example, string fields, or a mix of strings and dates), the scale type is categorical only.

The scale type is fixed for the variable. It does not change dynamically based on the field a viewer selects.

A variable can be added to a visualization only when the aggregation level of its fields matches the aggregation levels that the visualization accepts. For example, the x-axis and y-axis encodings of a heatmap accept disaggregated fields only, so they can encode only disaggregated variables.

Add a variable to a visualization

After you create a variable, add it to a visualization's encoding, such as an axis or a column. You can add the same variable to multiple visualizations. When a viewer changes the variable's selected field, every encoding that uses the variable updates to show the new field.