Tableau Desktop and Web Authoring Help

A parameter is a workbook variable such as a number, date or string that can replace a constant value in a calculation, filter or reference line.

For example, you may create a calculated field that returns True if Sales is greater than $500,000 and otherwise returns False. You can replace the constant value of “500000” in the formula with a parameter. Then, using the parameter control, you can dynamically change the threshold in your calculation.

To use a parameter, you must:

1. Set up the initial parameter.
2. Use the parameter in an element such as a calculation, filter or reference line.
3. Adjust the parameter value by:
   • Showing the parameter control
   • Using a parameter action
   • Setting a dynamic parameter to update automatically

Create a parameter

To create a parameter from the Data pane:

1. In the Data pane, click the drop-down arrow in the upper right corner and select Create Parameter.

   

2. In the Create Parameter dialog box, give the field a Name.

   

3. Specify the data type for the values it accepts:

   

4. Optional: Specify a current value. This is the default value for the parameter.
5. Optional: Specify a value when the workbook opens.
6. Specify the display format to use in the parameter control (Tableau Desktop only).

   

7. Specify how the parameter accepts values. You can select from the following options:
   • All: The parameter control is a simple text field.
   • List: The parameter control provides a list of possible values for you to select from.
     • If you select List, you must specify the list of values. Click in the left column to type your list of values, or you can add members of a field or paste from the clipboard by selecting Add values from.

       

   • Range: The parameter control lets you select values within a specified range.
     • If you select Range, you must specify a minimum, maximum and step size. The step size controls the jumps between values, such as letting you choose each number (5, 6, 7...) or going from 5 to 10 to 15.

   The availability of these options is determined by the data type. For example, a string parameter doesn't support Range.

   To refresh the parameter’s list of values (or domain) whenever the workbook opens, select List or Range, and then select When the workbook opens. Notice that some options are greyed out because the workbook is dynamically pulling values from the data source.

8. When finished, click OK.

The parameter is now listed in the Parameters section at the bottom of the Data pane.

Edit a parameter

You can edit parameters from the Data pane or the parameter control. Editing is for things like changing the allowable range or the data type. To simply change the value or a parameter, use the parameter control. See Show a parameter control in the viz.

To edit a parameter:

1. Do one of the following:
   • Right-click the parameter in the Data pane and select Edit.
   • Select Edit Parameter on the parameter control menu.
2. In the Edit Parameter dialog box, make your changes.
3. Click OK. The parameter is updated along with any elements that use it.

Delete a parameter

To delete a parameter, right-click it in the Data pane and select Delete. Any calculated fields that use the deleted parameter become invalid.

Use a parameter

A parameter won't do anything until it's tied to an element in the viz. Parameters can be referenced in calculations, filters and reference lines. Parameters are global across the workbook and can be used in any worksheet.

After the element references the parameter, be sure to Show a parameter control in the viz (or set up a parameter action, or a dynamic parameter). If there's no way to change the value of the parameter, it doesn't do any good to have it set up in the first place.

Use a parameter in a calculation

Parameters give you a way to dynamically modify values in a calculation. Rather than manually editing the calculation (and all dependent calculations), you can use a parameter. Then when you want to change the value, you open the parameter control, change the value and all calculations that use that parameter are updated.

To use a parameter in a calculation, type the name of the parameter and it appears in the suggested options, just like typing a field name. You can also drag the parameter from the Data pane and drop it in the calculation editor.

Use a parameter in a filter

Parameters give you a way to dynamically modify values in a Top N filter. Rather than manually setting the number of values you want to show in the filter, you can use a parameter. A list of parameters is available in the drop-down lists on the Top tab of the Filter dialog box. Select the parameter you want to use in the filter.

Use a parameter in a reference line

Parameters give you a way to dynamically modify a reference line, band, or box. For example, instead of showing a reference line at a fixed location on the axis, you can reference a parameter. Then you can use the parameter control to move the reference line.

A list of parameters is available in the Value drop-down list in the Add Reference Line, Band or Box dialog box. Select the parameter you want to use. The reference line is drawn at the Current Value specified by the parameter.

Show a parameter control in the viz

The parameter control is a worksheet card that lets you modify the parameter value. Parameter controls are similar to filter cards in that they contain controls that modify the view. You can open parameter controls on worksheets and dashboards and they’re included when you save to the web or publish to Tableau Server.

To open the parameter control, right-click (Control-click) the parameter in the Data pane and select Show Parameter.

Like other cards, parameter controls have a menu that you can open using the drop-down arrow in the upper right corner of the card. Use this menu to customise the display of the control. For example, you can show a list of values as radio buttons, a compact list, a slider, or a type in field.

The options available on this menu depend on the data type of the parameter and whether it accepts all, a list or a range of values.

Make a dynamic parameter

Parameter actions

You can make your parameters more dynamic and interactive by using them in Parameter Actions. Parameter actions let your audience change a parameter value through direct interaction with a viz, such as clicking or selecting a mark.

Dynamic current value

You can create a parameter that can refresh its current value to the result of a calculation, a list of values (based on a field) or a range of values. This refresh happens each time the workbook is opened or whenever you select Refresh from the data source’s context menu.

Use a calculation as the current value of a parameter

If the current value is the result of a calculation, it must be a single-value, view-independent calculation. If the calculation's result could be more than one value, the workbook can't choose a default value. The calculation must also be view-independent so that the value won’t change as the viz changes.

To do this, you can use a FIXED level of detail (LOD) expression that isn’t dependent on the structure of the viz. All parts of the calculation must be inside the FIXED LOD expression. If you use a FIXED LOD expression as the default value and are using context filters, the dynamic parameter won’t reflect any context filters.

For more information on LOD expressions, see Create Level of Detail Expressions in Tableau.

Note: We don't recommend using a dynamic parameter in a data extract filter because it impacts performance. If you use a dynamic parameter for a data extract filter, Tableau needs to first process all the data to determine the value of the parameter, and thus which data to filter. For example, if you use a dynamic parameter filter to return the last 30 days of data, Tableau evaluates the entire data source to find the last 30 days of data and then filters it. This results in reduced performance and a longer time to load.

Troubleshoot parameters

Here are a few scenarios when a default parameter value or a refreshable list of parameter values (domain) won’t update as expected:

• The default field returns a value whose data is incompatible with the parameter’s data type.
• The default field for the parameter's current value doesn’t return a single value.
• The default field returns null.
• The default field is in a data source that isn't connected.
• The default field was deleted.
• The user cancels the query to the data source while Tableau is attempting to connect.

In Tableau Desktop, these queries are initially evaluated when the workbook is opened and Tableau connects to the fields’ data sources for the first time. You can also evaluate the queries by refreshing the data source. To do this, press F5, or open the data source’s context menu and select Refresh. On Tableau Server and Tableau Cloud, you can refresh the data source by clicking the Data Source Refresh button in the toolbar. In this case, however, remember that the value returned depends on the server's cache policies.

If the default fields fail to return values, the parameter behaves as follows:

• The current value keeps the latest valid value.
• The list of values are empty because Tableau doesn’t serialize the values returned from the query in the workbook.

The current value must be in the list of values for it to be assigned to the parameter. If the list of values is empty, the parameter will get assigned a fallback value according to the data type (1 for integer, 1.0 for float, "" for string, and the current date for date and datetime).

Other articles in this section