Press CTRL+K to open search

Using Jinja to retrieve parameters from the URL

  • Updated on Nov 9, 2026
  • Published on Nov 9, 2026
  • 5 minute(s) read
Prev Next

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

To set the value of a dashboard's native filters from the URL, you don't need Jinja. See 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).

  • 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:

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

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:

    {% 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).

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:

    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.

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 or dataset permissions instead.