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. To show viewers a different label for an option, see Set display names for field options.

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.

Set display names for field options

Each field option in a dashboard variable has a generated label that combines the field name with its transform, such as Sum of sales or Average price. You can replace that label with a display name that viewers see instead, such as Total revenue. A display name changes only the label. The option's field and transform stay the same.

To set a display name for a field option:

1. On the draft dashboard, select the filter widget that controls the variable.

2. In the widget's configuration panel, under Variables, click the variable.

3. Under Field options, click the field option that you want to rename.

4. In the Display name box, enter the name. The box shows the generated label as a placeholder.

   

The display name saves as you type. To return to the generated label, clear the Display name box.

The display name appears wherever the dashboard shows the option, on both draft and published dashboards:

• The filter widget's list of options.
• The active filter bar and the widget filter indicator.
• Axis titles, legends, series names, and tooltips in visualizations that use the variable.

If you set a display name for a field in the visualization editor, that name takes precedence over the option's display name in that visualization.

You can also ask Genie Code for dashboard authoring to set, rename, or clear display names for a variable's field options. When Genie Code edits the variable, it keeps the display names you set.

Display names have the following limitations:

• A display name can contain up to 500 characters. Leading and trailing spaces are removed.
• When you export a dashboard to a .lvdash.json file or import one, display names for field options aren't included. Options in the exported or imported dashboard use their generated labels.

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.