Manage Query Parameters

With parameters, you can prompt for values to use with a query's filters or calculations each time it runs. By setting these values at runtime, you can use a query in a different context—such as account, region, or time period—each time it runs. You can create parameters to use with the specific query, or your workspace owner may create global parameters for use with multiple queries.

Create Parameters for a Query

You can create a query's parameters in either Builder or SQL Editor. When you create a parameter, you can use it with multiple filters and calculations in the query. 

Step 1. Create the Parameter

1. From the Parameters panel, click Create Parameter.
   
2. To help identify the parameter, enter a unique name with only alphanumeric characters and no spaces.
3. In Filter type, select the type of data to filter by, such as Text or Integer.

Step 2. Set Up the Parameter's Values

When a query runs, its parameters can accept freeform values—based on the data type—or provide a list of specific values to choose from. 

• To accept any freeform value, enter the default (if applicable), and click Create.
• To provide a list of specific values:

1. Enable Pick List.
   
2. To enable multiple values for the parameter, select Multi-Select.
3. In List Options, enter the values to choose from, pressing Enter after each.

   Note: For a date or timestamp parameter, enter each option in the YYYY-MM-dd format.

4. Select any default value for the parameter, and click Create.

   Note: For a multi-select parameter, select at least one default value.

Step 3. Use the Parameter in the Query

To apply the parameter's value to the query, use it in a filter or calculation:

• To set a filter's value based on the parameter in Builder, select it when you define the filter from the Filter Properties right panel.

  Note: For a multi-select parameter, select a filter operator of Is In List or Is Not In List on the Filters tab.

• To use the parameter with a filter in SQL Editor or reference its value in a calculation, enter its name after a colon (:) in the SQL statement, such as :ReportingPeriod.

Edit a Query Parameter

To adjust or manage the details of a parameter:

1. From the Parameters panel, select the parameter to edit.
2. Edit the parameter's name, data type, or values as necessary.
3. Click Apply.

Remove a Query Parameter

If you no longer need a parameter, you can remove it from the query. From the Parameters panel, click the parameter's Delete , and click Save .