Tableau Prep Help

Supported in Tableau Prep Builder version 2021.4.1 and later and on the web in Tableau Cloud and Tableau Server version 2021.4.0 and later

Note: The content in this topic applies to authoring flows in Tableau Prep Builder and on the web, unless specifically noted. For more information about authoring flows on the web, see Tableau Prep on the Web in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) help.

If you often reuse flows using different data with the same schema, you can create and apply user parameters to your flows to easily transition between scenarios. A parameter is a global placeholder value such as a number, text value, or boolean value that can replace a constant value in a flow.

Instead of building and maintaining multiple flows, you can now build one flow and use parameters to run the flow with your different data sets. For example, you can create a parameter for various sales regions, then apply a parameter value to the input file path to run the flow using just that region's data.

Starting in Tableau Prep Builder and Tableau Cloud version 2023.2, you can also add system parameters to the file or published data source output name to automatically add a time stamp each time you run the flow.

Where can I apply parameters?

You can apply user Parameters to file names, paths, table names, filter expressions, and calculated fields, depending on the step type. Starting in version 2022.1.1, you can even include parameter override values when running flows using the REST API. For more information, see Flow Methods(Link opens in a new window) in the Tableau Rest API help.

You can apply system parameters (version 2023.2 and later) to output names for file and published data source output types.

The following table lists the locations where you can apply parameters for each step type.

Step type	Parameter location
Input	User parameters: Connect to file: Use parameters in the file name or file path Connect to database: Use parameters for the table name and in Custom SQL Expression editor: Filters
Output	User or system parameters: Output to file: Apply user parameters to the file name or file path and starting in version 2022.1.1, to the Microsoft Excel worksheet name. Apply system parameters to the file name. Output to server: Apply user or system parameters to the published data source name Output to database: Apply user parameters to the table name and starting in version 2022.1.1, to SQL scripts that you run before or after writing the flow output to a database.
Clean, New Rows, Pivot, Join, Union	User parameters: Expression editor: Filters and calculated field values
Aggregate	User parameters: Expression editor: Filters
Script	User parameters: Expression editor: Filters and calculated field values
Prediction	User parameters: Expression editor: Filters and calculated field values

 

Create user parameters

User parameters are specific to the flow where they are used. Create parameters from the top menu, then define the values that apply to them. You can also define parameters that accept all values, which means any flow user can enter any value when running the flow.

You can make flow parameter values required or optional. When running the flow, users are prompted to enter the parameter values. Required parameter values must be entered before the user can run the flow. Optional parameter values can be entered or you can accept the current (default) value. The parameter values are then applied to the flow run everywhere that parameter is used.

Note: To run or schedule flows that include parameters on Tableau Server or Tableau Cloud, your administrator must enable the Flow Parameter settings on your server. For more information, see Create and Interact with Flows on the Web in the Tableau Server(Link opens in a new window) or Tableau Cloud(Link opens in a new window) help.

1. From the top menu, click the Parameter icon, then click Create Parameter.

   

2. In the Create Parameter dialog, enter a name and a description (optional). The parameter name must be unique. This is the value that shows in the user interface when you add a parameter.

   If you include a description, users can see this information on hover (starting in version 2022.1.1) in the parameters list and where parameters are used.

   

3. Select one of the following data types. Parameter values must match the data type that you select.

   • Number (whole or decimal)
   • String
   • Boolean

4. Specify the Allowable values.  These are the values that users can enter in the parameter.

   • All: This option lets users type in any value for the parameter, even when running the flow.

     Note: Using this option for parameters that can be used in input and output steps can be a security risk. For example, Custom SQL queries that allow any value to be entered can expose your data assets to SQL injection attacks.

   • List: Enter a list of values that users can choose from when applying the parameter. To enter multiple values, press Enter after each entry.
5. (optional) Select Require selection at run time (Prompt for value at run time in prior releases). This makes the parameter required. The user is required to enter a value when running or scheduling the flow.

6. Enter a Current value. This is a required value and acts as a default value for the parameter.

   • All: Enter a value.
   • List: Tableau uses the first value in your list. Use the drop-down option to change it.
   • Boolean: Select True or False.
7. Click OK to save the parameter.

Change the user parameter default value

When you create a user parameter, you have to specify a current (default) value. If a parameter is included in a flow, this value is used to:

• Run Custom SQL queries defined in an input step.
• Fill in optional parameters that aren't specified at run time.
• Replace the parameter as a static value in saved steps (version 2022.1.1 and later).
• Replace the parameter as a static value in file paths when publishing flows with packaged data sets.

You can change the value at any time. From the top menu you can edit the parameter or use the Set button on the parameter list. From within the flow, you can use the Set button anywhere the parameter is applied. When you do this, it resets the parameter's current (default) value everywhere that parameter is used, even in Custom SQL queries.

Edit user parameters

1. From the top menu, click the Parameter icon.
2. Click Edit parameter.

3. In the Edit Parameter dialog, make any changes, then click OK.

   

Reset user parameter default values

To quickly reset the parameter default value, use the Set button. The button shows you a count indicating the number of places in the flow where the parameter is used.

To highlight the steps in the flow that use the parameter, click View in flow on the parameter dialog. If there is only one place the parameter is used, you are taken directly to that step with the profile pane opened.

1. Do one of the following:

   • From the top menu, click the Parameter icon. Use this option to reset parameter values used anywhere in the flow, or when used in filters and calculated fields.

     

   • Click on the parameter where it is applied in the flow. You can use this option for parameters used in file names, file paths, table names, custom SQL, and pre and post SQL scripts.

     

2. Select or enter the parameter value.

3. Click Set to apply the change.

Apply parameters to your flow

After you create user parameters, you can apply them to various places throughout your flow, depending on the step type. When the flow is run, the parameter values are applied to that flow run to produce the output for the specific data scenario.

System parameters (version 2023.2 and later) are automatically generated when you run the flow. Simply apply them to your output step name and every time the flow is run, the parameter is dynamically updated with the flow run start date or time.

Apply parameters to input steps

In an Input step you can use user parameters to replace a file name, sections of your file path, a database table name, or when using Custom SQL.

File name or file path

This option is not available when editing or authoring flows on the web.

You can include user parameters in your file path with some exceptions. Starting in version 2022.1.1, you can also see a preview of the parameter values.

Exceptions

• Starting in version 2022.1.1, you can schedule and run flows on the web that include parameters in the input file path. If using an earlier version, run flows in Tableau Prep Builder or from the command line.

• To include parameters in the file path when publishing flows to the web, a direct file connection is required. Otherwise, the parameter is converted to a static value using the Current value.

  Note: Direct file connections require that the file locations are included in your organization's safe list. For more information see Safe List Input and Output Locations(Link opens in a new window) in the Tableau Server help.

Apply a user parameter to a file name or path

1. In the Settings tab, in the file path, place your cursor in the location where you want to add the parameter.

2. Click the parameter icon and select your parameter.

   

3. View a preview of the parameter value. The current (default) value is shown in the preview. You'll be prompted to select or enter the parameter value when you run the flow.

   

Database table

When using user parameters in table names, the entire table name must be the parameter. Using parameters for parts of a table name is not currently supported.

Note: Using a parameter for a table name in a Google BigQuery input connection is not yet supported.

1. In the Settings tab, in the Table field, click the drop-down menu.

2. Select Use Parameter, then select the parameter from the list.

   

Custom SQL

1. In the Connections pane, click Custom SQL.

2. In the Custom SQL tab, type or paste the query into the text box.

3. Click the parameter icon and select your parameter.

   

4. Click Run to run your query. You won't be prompted to enter a parameter value until you run the flow. Instead the query will run initially using the parameter's Current value.

   Note: If the parameter is used elsewhere in the flow and the Current Value is reset, that change can impact your query.

Apply user parameters to output steps

In an Output step you can apply user parameters to the following places:

• File name
• Sections of your file path
• Published data source name
• Database table name
• Microsoft Excel worksheet name (version 2022.1.1 and later)
• Custom SQL scripts that run before or after writing flow output data to a database (version 2022.1.1 and later)

File name or file path

This output option is not available when creating or editing flows on the web

1. In the Output pane, select File from the Save output to drop-down list.

2. In the Name or Location field, click the parameter icon and select your parameter.

   For file path, place your cursor in the location where you want to add the parameter.

   

   When you run the flow you'll be prompted to enter your parameter values.

Published data source name

1. In the Output pane, in the Save output to drop-down list, select Published data source.

2. In the Name field, click the parameter icon and select your parameter.

   

   When you run the flow you'll be prompted to enter your parameter values.

Database table and Before and After Custom SQL

1. In the Output tab, in the Save output to drop-down list, select Database table.

2. In the Table field, select Use Parameter, then select the parameter from the list.

   

3. (Optional) Click on the Custom SQL tab. Starting in version 2022.1.1, you can enter a SQL script with parameters to run Before and After the data is written to the table. To include a parameter, click Insert Parameter, and select your parameter.

   For more information about using SQL scripts when writing output to a database, see Save flow output data to external databases.

   Note: Parameters used in SQL scripts must be manually deleted. See Manually delete user parameters for more information.

   

   When you run the flow you'll be prompted to enter your parameter values.

Apply system parameters to output steps

In an Output step you can apply date and time system parameters to the following places:

• File name
• Published data source name

File name

This output option is not available when creating or editing flows on the web

1. In the Output pane, select File from the Save output to drop-down list.

2. In the Name field, click the parameter icon and select from the following run date or run time parameters. You can combine multiple system parameters to create whatever time stamp you need.

   Run date

   • Date: YYYY-MM-DD, YYYMMDD, DD-MM-YYYY
   • Month: Month Name, Month Number
   • Week Number
   • Quarter Number
   • Year Number

   Run time

   • YYYY-MM-DD_HH-MM-SS (24 hour)
   • YYYYMMDD_HHMMSS (24 hour)

   When you run the flow Tableau Prep applies the flow start run time using your local time zone or the server time zone.

Published data source name

1. In the Output pane, in the Save output to drop-down list, select Published data source.

2. In the Name field, click the parameter icon and select from the following run date or run time parameters. You can combine multiple system parameters to create whatever time stamp you need.

   Run date

   • Date: YYYY-MM-DD, YYYMMDD, DD-MM-YYYY
   • Month: Month Name, Month Number
   • Week Number
   • Quarter Number
   • Year Number

   Run time

   • YYYY-MM-DD_HH-MM-SS (24 hour)
   • YYYYMMDD_HHMMSS (24 hour)

   When you run the flow Tableau Prep applies the flow start run time using your local time zone or the server time zone.

Apply user parameters to filter calculations

Use user parameters to filter data throughout your flow. Filter your data set in the input step or apply filter parameters at the step or field value level. For example use a filter parameter to only input data for a specific region or filter data in a step to a specific department.

Note: Starting in version 2022.1, you can use copy and paste to reuse filter calculations with parameters in other flows when the same parameter exists with the same name and data type.

1. From the Input step or toolbar on the profile pane, click Filter Values. To add a parameter filter to a field, from the More optionsmenu select Filters > Calculation.

2. In the Add Filter calculation editor, type the name of the parameter to select it from the list (the parameter shows in purple), then click Save to save your filter.

   

   When you run the flow you'll be prompted to enter your parameter values.

Apply user parameters to calculated fields

Use user parameters to replace constant values in calculations that you use throughout your flow. You can apply calculation parameters at the step or field value level.

Note: Starting in version 2022.1, you can use copy and paste to reuse calculations with parameters in other flows when the same parameter exists with the same name and data type.

1. From the toolbar on the profile pane, click Create Calculated Field. To add a parameter to a calculation on a field, from the More optionsmenu select Create Calculated Field > Custom Calculation.

2. In the Add Field calculation editor, enter your calculation, type the name of the parameter to select it from the list, then click Save to save your calculation.

   

   When you run the flow you'll be prompted to enter your parameter values.

Delete user parameters

To delete user parameters that you no longer need, click Delete Parameter in the Edit Parameter dialog. This removes any instance of the parameter used throughout the flow and replaces it with the parameter's Current value. This action can't be undone.

Note: The options to delete parameters in a flow vary depending on your version. Use the instructions below for version 2022.1 and later. Use Manually delete user parameters for previous versions and to delete parameters used in Custom SQL scripts that run before or after writing output to a database.

1. From the top menu, click the parameter icon drop-down menu, then click Edit parameter for the parameter you want to delete.

2. In the Edit Parameter dialog, click Delete Parameter.

   

3. In the confirmation dialog, click Delete Parameter again. You can click View in flow to highlight the steps and investigate where the parameter is used before you delete it.

   

Run flows with parameters

Running flows that include parameters is the same as running flows that don't have them, except that users are prompted to enter user parameter values at run time or when adding the flow to a schedule in Tableau Server or Tableau Cloud.

System parameters are applied automatically when the flow is run.

If a user parameter is marked as a required, users must enter a value before they can run the flow. If a parameter is optional, users can enter a value or accept the parameter's Current value by default.

Required parameters are those that have the Require selection at run time (Prompt for value at run time in prior releases) check box selected.

If you run flows using the command line interface and want to override the current (default) parameter values, create a parameters override .json file and include the -p --parameters syntax in your command line. For more information, see Refresh flow output files from the command line.

Run flows manually

When you run a flow from Tableau Prep Builder or manually in Tableau Server or Tableau Cloud, the Parameters dialog opens when you click Run.

1. Enter or select the user parameter values. If there are optional parameters in the flow, you can enter the values at this time or accept the current (default) parameter value.
2. Click Run Flow to run the flow.

For more information about running flows, see Publish a Flow to Tableau Server or Tableau Cloud.

Run flows on a schedule

When you schedule flows to run on Tableau Server or Tableau Cloud, you will need to enter any required user parameter values when scheduling the flows.

1. On the New Tasks or Linked Tasks tab, in the Set Parameters section, enter or select the parameter values. If there are optional parameters in the flow, you can enter the values at this time or leave the field empty to use the current (default) parameter value.

2. Click Create Tasks to schedule your flow.