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 custom parameters to use with a specific query, or your workspace owner may create global parameters for use with multiple queries.

Create custom parameters for a query

You can set 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 Add, and select Create New 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 Picklist.
2. To enable multiple values for the parameter, check the Multi-Select box.
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 Accept.

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

5. Click Create to finish.

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.

Use global parameters in a query

Your workspace owner may configure global parameters for common values used with multiple queries. To use global parameters in a query:

1. From the Parameters panel, click Add, and select Select Global Parameter.
   
2. Select the global parameters to use in the query, and click Add.
3. To edit the global parameter, select it and update its name or value as necessary for the query.

   Note: To ensure consistent analysis, your workspace owner may lock a global parameter to prevent its value from being edited.

4. To apply a global 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 reference the parameter in SQL Editor, enter its name after a colon (:) in the SQL statement, such as :ReportingPeriod.
   • To reference a parameter value in a calculation's SQL statement, select the parameter from the Parameters menu.

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 .