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. Once you create parameters, they are available as configuration variables in gems wherever you can select a visual expression. You can also reference parameters using Jinja syntax in code expressions.

​

Use parameters in pipelines

To use parameters in pipelines:

1. Add any gem that uses expressions, such as a Filter or Reformat gem.
2. Open the gem configuration. Ensure you are in the Visual tab.
3. Select Configuration Variables from an Expression dropdown menu.

You can use Jinja syntax to add parameters as configuration variables in the Code tab. To do so, use the following syntax: {{ var('disc_rate') }}. You can also use Jinja syntax in the Visual tab by using the Custom code expression. For more information on Jinja variables, see dbt’s documentation on Jinja. By default, the parameter’s value will be used for the expression, though this value can be overwritten in both pipeline gems and Prophecy Apps.

Example: If you create a parameter called start_date with a value of 2025-09-01, you can use it in a Filter gem to include only rows where order_date >= start_date. When the pipeline runs, it injects the parameter’s value into the filter expression.

​

Use parameters in Prophecy Apps

Parameters are useful in both creating and consuming Prophecy applications. To use parameters in a Prophecy App, add an input field and select the parameter for Configuration field.

​

Array example

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 your project and select Parameters in the header.
2. Click + Add Parameter.
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 Array parameter in a Filter gem

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.
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.

​

Create a Prophecy App to adjust region filters

1. Add a Prophecy App called regional_sales.
2. Add a title for the app.
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 app 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 example

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 your pipeline and select Parameters in the header.
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 Date parameters in a Filter gem

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.

​

Create a Prophecy App with date fields

1. Add a Prophecy App called sales_snapshot.
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 app runs, users can select their own values for start_date and end_date.

​

String example

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 your project and select Parameters in the header.
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 String parameter in a Filter gem

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.

​

Create a Prophecy App to select customer groups

1. Add a Prophecy App called customer_segment.
2. Add a title for the app.
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 app runs, users can switch the customer_type parameter from Premium to Standard (or another category) to explore different customer groups.

​

Boolean example

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 a Prophecy App that lets users choose whether to include archived reviews. First, you’ll set up an include_archived parameter, which will be a Boolean value.

1. Open your project and select Parameters in the header.
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 Boolean parameter in an expression

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 a Prophecy App that lets users change include_archived to true.

​

Create a Prophecy App to show archived data

1. Add a Prophecy App called Reviews.
2. Add a Title for the app.
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 app runs, users can toggle Include archived reviews? to include archived reviews in results.

​

Double example

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 a Prophecy App that lets users adjust this rate. First, you’ll set up a discount_rate parameter of type Double.

1. Open your project and select Parameters in the header.
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 Double parameter in an expression

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.

​

Create a Prophecy App to show discounted products

1. Add a Prophecy App called products_with_reviews.
2. Add a title for the app.
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 app runs, users can enter their own rate for discount_rate.

​

Long example

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 your project and select Parameters in the header.
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.

​

Compute total usage per subscriber, then filter with the Long parameter

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.

​

Create a Prophecy App to adjust the cap

1. Add a Prophecy App called usage_cap_monitor.
2. Add a title for the app.
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 app runs, users can raise or lower the cap by changing usage_cap_mb to see which subscribers are affected.

​

Float example

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 your project and select Parameters in the header.
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 Float parameter in a Filter gem

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.

​

Create a Prophecy App to adjust sensitivity

1. Add a Prophecy App called temperature_monitor.
2. Add a title for the app.
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 app 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.