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.

By default, a viewer selects one field at a time. You can also let viewers select several fields at once, so that a single variable adds multiple series, columns, or rows to a visualization. See Let viewers select multiple fields.

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. 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 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.

Each field option in a dashboard variable shows its source dataset as a subtitle, so you can distinguish fields that share a name across datasets.

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.

Let viewers select multiple fields

Multi-select lets dashboard viewers display several of a variable's fields at once, so a single variable adds a separate series, column, or row for each selected field. For example, a viewer can show both Sales and Profit as separate series on the same chart. By default, a variable substitutes a single field.

To enable it, turn on Allow multi-select when you create or edit the variable. Viewers then use a multi-select control to choose any combination of the variable's fields, and every visualization that uses the variable adds one entry per selected field.

Multi-select works only on encodings that can display more than one field, such as:

• The y-axis of a multi-series bar or line chart
• The columns of a table
• The rows, columns, or values of a pivot table

If you add a multi-select variable to an encoding that can show only one field (for example, a counter value or a chart's x-axis), the visualization uses only the first selected field and shows a warning.