> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prophecy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use parameters

> Reference parameters in pipelines and analysis dashboards

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](/data-analysis/analysis/overview) or [deployment](/data-analysis/production/publication).

<Info>
  To learn how to create and define new parameters, see the [parameters
  overview](/data-analysis/development/parameters/parameters).
</Info>

## 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](/data-analysis/gems/) that uses visual or code expressions, such as a [Filter](/data-analysis/gems/prepare/filter) or [Reformat](/data-analysis/gems/prepare/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') }}`.

   <Tip>
     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](https://docs.getdbt.com/reference/dbt-jinja-functions/var).
   </Tip>

Prophecy determines the parameter's value based on the [active parameter set](/data-analysis/development/parameters/parameter-sets). 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](/data-analysis/analysis/overview) so that end users can select the regions they want to see in a report.

1. Create an [analysis](/data-analysis/analysis/create-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](/data-analysis/analysis/create-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](/data-analysis/analysis/create-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](/data-analysis/analysis/create-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](/data-analysis/gems/prepare/reformat).
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](/data-analysis/analysis/create-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](/data-analysis/analysis/create-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.

### Connection type

This example uses a pipeline that reads data from Amazon S3. You can use a **Connection** parameter to make the pipeline reusable across fabrics and environments.

#### Create the Connection parameter

1. Open the pipeline parameter settings for the relevant pipeline.
2. Click **+ Add Variable**.
3. Name the parameter `sales_s3_connection`.
4. Select the **Type** and choose **Connection**.
5. Select a connection from the current fabric, such as `s3_sales_dev`.
6. Click **Save**.

The selected connection becomes the default value for the parameter.

#### Use the parameter in a Source gem

Next, you'll configure a Source gem to use the connection parameter instead of a fixed connection.

1. Add an **S3 Source** gem to your pipeline.
2. Open the Source gem settings.
3. In the **Connection** field, select **Configuration Variable**.
4. Select `sales_s3_connection`.
5. Configure the remaining source settings, such as bucket and file path.
6. Click **Save**.

Only connection parameters matching the Source gem type are selectable. For example, an S3 Source gem only allows S3 connection parameters.

#### Switch fabrics

If you switch to another fabric, Prophecy validates that the configured connection still exists and matches the expected type.

Diagnostics appear in the Source gem if:

* The selected connection does not exist in the current fabric.
* A connection with the same name exists, but the connection type does not match the Source gem type.

For example, if `sales_s3_connection` references an S3 connection in one fabric, but the same connection name refers to a Snowflake connection in another fabric, the Source gem displays a diagnostic error.

## 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](/data-analysis/environment/secrets/secrets) rather than passing them as plain parameters.