---
title: "Using Jinja to retrieve parameters from the URL"
slug: "using-jinja-url-params"
updated: 2026-11-09T20:41:07Z
published: 2026-11-09T20:41:07Z
canonical: "docs.preset.io/using-jinja-url-params"
---

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

# Using Jinja to retrieve parameters from the URL

## Overview

This article covers how to use Jinja templating to read URL parameters and use them in datasets, charts, saved queries and dashboards. For example, a link ending in `?quarter=2` can show the same chart filtered to the second quarter, without creating a separate chart.

![Adding quarter=2 and metric=sum to a dashboard URL updates the charts](https://cdn.document360.io/4749ddf8-aa05-4f3f-80e1-07a5d2d0f137/Images/Documentation/2026-11-09_16-49-54 (1).gif)

> To set the value of a dashboard's **native filters** from the URL, you don't need Jinja. See [Filtering dashboards with URL parameters](/v1/docs/filtering-dashboards-with-url-parameters). Use `url_param()` when you need a custom parameter that your SQL reads directly.

---

## How url_param() works

`url_param('name')` returns the value of the URL parameter `name`. With the URL `...?country=France`, `{{ url_param('country') }}` renders as `France`.

- **The value is inserted without quotes.** For text values, add the quotes yourself: `country = '{{ url_param('country') }}'`.
- **A missing parameter renders as** `None`. Either wrap the condition in `{% if url_param('country') %} ... {% endif %}`, or set a default value: `url_param('country', default='USA')`.
- **Quotes in the value are escaped** for your database. For example, `O'Brien` becomes `O''Brien`, so the value can't close the quotes around it.
- **Where the value comes from:** the URL of the chart (Explore), of the dashboard the chart is on, or of SQL Lab. In embedded dashboards, pass parameters with the `urlParams` option of the Embedded SDK (see [Step 2: Deployment](/v1/docs/step-2-deployment)).
- Each parameter value is cached separately, so changing the parameter returns fresh results.

The full signature is `url_param(param, default=None, add_to_cache_keys=True, escape_result=True)`.

---

## Configuring the asset to retrieve the URL parameter

URL parameters can be used in dataset definitions, chart configurations and saved queries. In all cases, the syntax is the same: the `url_param()` Jinja macro.

The following sections cover each scenario. They use the `Vehicle Sales` table from the `examples` database connection.

### 1. Fetching URL parameters in the dataset query

The `url_param()` macro can be used in the SQL query of a virtual dataset, and in metric and calculated column definitions. The following example uses this SQL query:

```sql
select order_date, order_number, product_line, price_each, country, quarter
from "Vehicle Sales"
where 1=1
{% if url_param('quarter') %}
  and quarter = {{ url_param('quarter') | int }}
{% endif %}
```

`quarter` is a number, so the value isn't quoted. The `| int` filter converts it to a whole number, so only numbers can reach the query (see [Security and good practices](/docs/using-jinja-url-params#security-and-good-practices)).

To do so:

1. Access your Workspace.
2. Navigate to **SQL > SQL Lab**.
3. Make sure that the `examples` database connection is selected in the **Database** dropdown.
4. Paste the SQL query and click **Run** to confirm it works. Without the parameter, the query returns all quarters.
5. Click the arrow next to **Save** and select **Save dataset**.
6. Enter a name for your dataset and click **Save & Explore**.
7. The page opens a **Table** chart. Set the query mode to **Aggregate** and select `quarter` as the dimension.
8. Set `COUNT(*)` as the metric and click **Update chart**.
9. Click **Save** in the top right corner, and fill in the dialog to create the chart.
10. After the page reloads, click in the browser's address bar, add `&quarter=1` at the end of the URL, and press Enter.

The chart now shows only the first quarter. The same approach works in calculated columns and metrics defined in the dataset.

### 2. Fetching URL parameters in the chart configuration

You can also use URL parameters directly in the chart builder, in custom SQL dimensions, metrics and filters. To do so:

1. Create a chart using the `Vehicle Sales` dataset from the `examples` database connection.
2. Set any column as the dimension.
3. Add a metric, open the **Custom SQL** tab and enter:

```sql
{% if url_param('metric') == 'sum' %}
  SUM(price_each)
{% elif url_param('metric') == 'avg' %}
  AVG(price_each)
{% else %}
  COUNT(*)
{% endif %}
```

Here the value is only compared inside Jinja and never inserted into the SQL, so no quotes are needed. Only the three listed expressions can reach the query.
4. Give the metric a name and save it.
5. Click **Update chart**.
6. Click the ellipsis menu (**...**) next to **Save** and select **View query**. Note that `COUNT(*)` is used.
7. Click in the browser's address bar, add `&metric=sum` at the end of the URL, and press Enter.
8. Open **View query** again and confirm that `SUM(price_each)` is used.

If you add this chart to a dashboard, you can also add the parameter to the dashboard URL (see [Using this feature on dashboards](/docs/using-jinja-url-params#using-this-feature-on-dashboards)).

### 3. Fetching URL parameters in a saved query

You can also save a SQL query that uses URL parameters. To do so:

1. Navigate to **SQL > SQL Lab**.
2. Make sure the `examples` database connection is selected in the **Database** dropdown, and paste the following SQL query:

```sql
select country, SUM(price_each) as revenue
from "Vehicle Sales"
where 1=1
{% if url_param('country') %}
  and country = '{{ url_param('country') }}'
{% endif %}
group by 1
```

`country` is text, so the value is wrapped in single quotes.
3. Click **Run**. Without the parameter, the query returns all countries.
4. Click **Save**.
5. Enter a name for the saved query and click **Save**.
6. Navigate to **SQL > Saved Queries**.
7. Hover over the query and click the **Copy query URL** button in the **Actions** column.
8. Paste the URL in the browser's address bar, add `&country=USA` at the end, and press Enter.
9. Click **Run**.

The filter is applied and only data for `USA` is returned.

### Using this feature on dashboards

URL parameters also work in dashboard links. Every chart on the dashboard receives the dashboard's URL parameters. Keep in mind that:

- Charts must be configured to use the URL parameter, either in the dataset or in the chart itself. Charts that don't use it are not affected.
- Native filters still apply on top of the URL parameter. For example, with `?country=France` and a Country native filter set to USA, a chart filtered by both shows no results.
- If the dashboard URL has no `?` yet, start with `?` instead of `&`, for example `/superset/dashboard/12/?quarter=2`. Preset may add a `native_filters_key` parameter to the URL after the dashboard loads. This is expected, and your own parameters are kept.

For this example, create a sample dashboard that includes the charts created in sections 1 and 2:

1. Create a dashboard and add the charts from sections 1 and 2.
2. Save the changes and reload the dashboard.
3. In the browser's address bar, add `&quarter=2&metric=sum` at the end of the URL and press Enter.
4. Each chart updates based on the parameter it uses: the quarter chart shows only the second quarter, and the metric chart shows sums instead of counts.

![](https://cdn.document360.io/4749ddf8-aa05-4f3f-80e1-07a5d2d0f137/Images/Documentation/2026-11-09_16-49-54 (2)(1).gif)

To share the result, copy the URL from the address bar. Permalinks created with **...** > **Share** > **Copy permalink to clipboard** also keep the URL parameters.

---

## Security and good practices

Anyone who opens the link can change URL parameters, so treat their values as user input:

- **Quote text values:** `country = '{{ url_param('country') }}'`. Escaping protects values that are inside quotes.
- **Convert numbers with** `| int` **(or** `| float`**):** `quarter = {{ url_param('quarter') | int }}`. Without quotes or a conversion, a value such as `1 OR 1=1` is inserted into the SQL as is. With `| int`, anything that isn't a number becomes `0`.
- **Prefer a fixed list of options** when the parameter selects SQL (columns, functions, sort order). Compare the value in Jinja and write the SQL yourself, as in section 2.
- **Don't set** `escape_result=False`. It turns off escaping. Even legitimate values such as `O'Brien` then break the query.
- **Don't use URL parameters to restrict data access.** Users can remove or change them. Use [Row Level Security](/v1/docs/row-level-security-rls) or dataset permissions instead.

## Related articles

- [Parametrizing Queries Using Jinja](/v1/docs/parametrizing-queries-using-jinja)
- [Filtering dashboards with URL parameters](/v1/docs/filtering-dashboards-with-url-parameters)
- [Step 2: Deployment (embedded dashboards and urlParams)](/v1/docs/step-2-deployment)