Use parameters

Parameters let you define reusable variables that are injected into your pipeline at runtime. Instead of hard-coding values such as dates or file paths, you can reference parameters. This page describes how to operationalize existing parameters in your pipeline for analysis dashboards or deployment.

​

How do you use parameters in your pipeline?

Once you create parameters, they are available as configuration variables in gems. You can also reference parameters using Jinja syntax in code expressions. To access parameters in a gem:

1. Open any gem that uses visual or code expressions, such as a Filter or Reformat.
2. In Visual mode, select Configuration Variables from the visual expression builder. You’ll see a list of all existing parameters in your project.
3. In Code mode, use Jinja syntax instead. Use the following syntax to reference a parameter: {{ var('parameter_name') }}.
   You can also use Jinja syntax in the visual expression builder by including a custom code expression. For more information on Jinja variables, see dbt’s documentation on Jinja.

Prophecy determines the parameter’s value based on the active parameter set. By default, Prophecy uses the values in the default parameter set.

​

Examples

​

Array type

This example uses a dataset with a column called region. You can use an Array parameter called region_list to filter rows that match one of several regions.

​

Create the Array parameter

1. Open the pipeline parameter settings for the relevant pipeline.
2. Click + Add Variable.
3. Name the parameter region_list.
4. Select the Type and choose Array.
5. Select String for Array type.
6. Click + to add items to the array.
7. Click Value and enter US-East (or another region code).
8. Click Done.
9. Repeat steps 6-8 to add US-West and Europe to the Array parameter.
10. Click Save.

​

Use the parameter in a filter

Next, you’ll filter your dataset to only include rows where the region column matches a value in region_list.

1. Add a Filter gem to your pipeline.
2. Remove the default true expression.
3. Click Select expression.
4. Select Function > Array > array_contains.
5. Choose value > Configuration Variable.
6. Select region_list.
7. Click + to add an argument for array_contains and choose Region.
8. Click Save.
9. Add a Target table gem called sales_transactions_by_region and connect it to the Filter gem.
10. Click Save.

​

Adjust region from a dashboard

You can now select the parameter in an analysis dashboard so that end users can select the regions they want to see in a report.

1. Create an analysis for the regional_sales pipeline.
2. Add a title for the analysis.
3. Select Interactive > Checkbox Group.
4. Select region_list for Configuration field.
5. Add a region in Default value, such as US-East.
6. Add options such as US-East, US-West, Europe, Mexico, Brazil, LAC, and Andean.
7. Open the Data Integration dropdown and select Data Preview.
8. In the Inspect tab, choose sales_transactions_by_region.
9. Select columns to display.

When the analysis runs, users can check boxes to select their desired regions. For example, a sales team in Latin America might select Mexico, LAC,Brazil, and Andean to view their focus regions.

​

Date type

This example uses a dataset with timestamped sales data. You can use two Date parameters, start_date and end_date to configure a snapshot of sales data by a time period such as week or month.

​

Create the Date parameters

1. Open the pipeline parameter settings for the relevant pipeline.
2. Click + Add Parameter.
3. Name the parameter start_date.
4. Select Type and choose Date.
5. Click Select expression > Value.
6. Enter 09/01/2025 (or another default start date) and click Done.
7. Click Save.
8. Repeat the steps above to create an end_date parameter with a default value of 09/07/2025.

​

Use the parameters in a filter

1. Add a Filter gem to your pipeline.
2. Remove the default true expression.
3. Click Select expression.
4. Select Column and select sales_date (or your dataset’s date column).
5. Choose the between operator.
6. For both start_date and end_date, click Select expression > Configuration Variable and select corresponding parameters.
7. Add a Target table gem called snapshot_by_date and connect it to the Filter gem.
8. Click Save.

​

Adjust date from a dashboard

1. Create an analysis for the sales_snapshot pipeline.
2. Add a title.
3. Select Interactive > Date Field.
4. For Configuration field, choose start_date.
5. Add another Date Field and select end_date.
6. Open the Data Integration dropdown and select Data Preview.
7. In the Inspect tab, choose snapshot_by_date.
8. Select columns to display.

When the analysis runs, users can select their own values for start_date and end_date.

​

String type

This example uses a dataset with a column called customer_category with values such as Premium, Basic, and Standard. You can use a String parameter called customer_type to filter rows for a specific group of customers.

​

Create the String parameter

1. Open the pipeline parameter settings for the relevant pipeline.
2. Click + Add Parameter.
3. Name the parameter customer_type.
4. Select the Type and choose String.
5. Click Select expression > Value.
6. Enter Premium and click Done.
7. Click Save.

​

Use the parameter in a filter

Next, you’ll filter your dataset based on the customer_type parameter.

1. Add a Filter gem.
2. Remove the default true expression.
3. Click Select expression > Column and select customer_category.
4. Choose the Equals ( = ) operator.
5. Click Select expression > Configuration Variable.
6. Select customer_type.
7. Add a Target table gem called filtered_customers and connect it to the Reformat gem.
8. Click Save.

​

Adjust customer type from a dashboard

1. Create an analysis for the customer_segment pipeline.
2. Add a title for the analysis.
3. Select Interactive > Dropdown.
4. Give the dropdown a label.
5. Select customer_type for Configuration field.
6. Open the Data Integration dropdown and select Data Preview.
7. In the Inspect tab, choose filtered_customers.
8. Select the columns to display.

When the analysis runs, users can switch the customer_type parameter from Premium to Standard (or another category) to explore different customer groups.

​

Boolean type

This example uses a dataset of customer reviews, in which reviews older than 5 years are designated as archived, using a column called archived_reviews with Boolean values. You can use a Boolean parameter to create an analysis dashboard that lets users choose whether to include archived reviews.

​

Create the Boolean parameter

1. Open the pipeline parameter settings for the relevant pipeline.
2. Click + Add Parameter.
3. Name the parameter include_archived.
4. Select the Type and choose Boolean.
5. Click Select expression > Value.
6. Click False and click Done.
7. Click Save.

​

Use the parameter in a filter

Next, you’ll create a Filter gem that uses the include_archived parameter in an expression.

1. Create and open the Filter gem.
2. Remove the default true expression.
3. Click Select expression > Column and select archived.
4. In the Select operator dropdown, select equals.
5. In the Select expression dropdown of the Filter condition, select Configuration variable and select include_archived.
6. Add a Target table gem called prod_filtered_archived and connect it to the Filter gem.
7. Click Save.

The output of this gem will only include rows where include_archived is false. In the steps below, you’ll create an analysis dashboard that lets users change include_archived to true.

​

Adjust reviews from a dashboard

1. Create an analysis for the reviews pipeline.
2. Add a Title for the analysis.
3. Add a Toggle that uses include_archived as a Configuration field, with a label reading Include archived reviews?.
4. Open the Data Integration dropdown and select Data Preview.
5. In the Inspect tab, choose prod_filtered_archived for Data table.
6. Select columns to display.

When the analysis runs, users can toggle Include archived reviews? to include archived reviews in results.

​

Double type

This example uses a dataset that includes a column called discount_rate that applies a discount for customers in certain cases. You can use a Double parameter inside an analysis dashboard that lets users adjust this rate.

​

Create the Double parameter

1. Open the pipeline parameter settings for the relevant pipeline.
2. Click + Add Parameter.
3. Name the parameter discount_rate.
4. Select the Type and choose Double.
5. Click Select expression > Value.
6. Enter .15 and click Done.
7. Click Save.

​

Use the parameter in a reformat

Next, you’ll create a Reformat gem that uses the discount_rate parameter in an expression that uses Jinja syntax.

1. Add a Reformat gem.
2. Under Target Column, add price, product, and quantity.
3. Under Target Column, add a new column called discounted_price.
4. Click Select expression > Custom code and enter price * (1 - {{ var('discount_rate') }}).
5. Add a Target table gem called products_discounted and connect it to the Reformat gem.
6. Click Save.

​

Adjust discount rate from a dashboard

1. Create an analysis for the products_with_reviews pipeline.
2. Add a title for the analysis.
3. Select Interactive > Number Input.
4. Select discount_rate for Configuration field.
5. Give the field a label.
6. Open the Data Integration dropdown and select Data Preview.
7. In the Inspect tab, select products_discounted for Data table.
8. Select columns to display.

When the analysis runs, users can enter their own rate for discount_rate.

​

Long type

This example uses a dataset for a telecom company that includes aggregated usage data by month. You can use a Long parameter to set a monthly data cap in MB and flag or filter subscribers who exceed it.

​

Create the Long parameter

1. Open the pipeline parameter settings for the relevant pipeline.
2. Click + Add Parameter.
3. Name the parameter usage_cap_mb.
4. Select the Type and choose Long.
5. Click Select expression > Value.
6. Enter 50000 and click Done.
7. Click Save.

​

Use the parameter in a filter

1. Add a Filter gem.
2. Remove the default true expression.
3. Select Column > total_usage_mb.
4. Choose Greater than ( > ).
5. Click Select expression > Configuration Variable and select usage_cap_mb.
6. Add a Table gem called usage_over_cap and connect it to the Filter gem.
7. Click Save.

​

Adjust usage cap from a dashboard

1. Create an analysis for the usage_cap_monitor pipeline.
2. Add a title for the analysis.
3. Select Interactive > Number Input.
4. Select usage_cap_mb for Configuration field and label it Monthly Cap (MB).
5. Open Data Integration > Data Preview.
6. In the Inspect tab, choose usage_over_cap for Data table.
7. Select columns to display (e.g., subscriber_id, total_usage_mb, billing_period).

When the analysis runs, users can raise or lower the cap by changing usage_cap_mb to see which subscribers are affected.

​

Float type

This example uses dataset of sensor data with a column called sensor_temp. You can use a Float parameter called temperature_threshold to filter out rows below a certain temperature.

​

Create the Float parameter

1. Open the pipeline parameter settings for the relevant pipeline.
2. Click + Add Parameter.
3. Name the parameter temperature_threshold.
4. Select the Type and choose Float.
5. Click Select expression > Value.
6. Enter 72.1 and click Done.
7. Click Save.

​

Use the parameter in a filter

Next, you’ll use the temperature_threshold parameter to filter your data.

1. Add a Filter gem.
2. Remove the default true expression.
3. Select Column > sensor_temp.
4. Choose the Greater than ( > ) operator.
5. Click Select expression > Configuration Variable.
6. Select temperature_threshold.
7. Add a Table gem called filtered_temperature and connect it to the Filter gem.
8. Click Save.

​

Adjust temperature threshold from a dashboard

1. Create an analysis for the temperature_monitor pipeline.
2. Add a title for the analysis.
3. Select Interactive > Number Input.
4. Select temperature_threshold for Configuration field.
5. Give the field a label, such as Temperature Threshold.
6. Open the Data Integration dropdown and select Data Preview.
7. In the Inspect tab, choose filtered_temperature.
8. Select columns to display.

When the analysis runs, users can adjust temperature_threshold to make filtering more or less sensitive.

​

Best practices

To make the most out of parameters, we suggest you:

• Use meaningful parameter names that indicate their purpose.
• Validate inputs to prevent unexpected errors during execution.
• Keep sensitive values such as API keys in secrets rather than passing them as plain parameters.