Jinja Templating in Apache Superset: Practical Guide 2026

Jinja templating in Apache Superset allows writing parameterized and contextual SQL queries. Combined with virtual datasets and RLS, it offers huge flexibility to build dynamic and multi-tenant dashboards. This guide explains useful patterns in 2026.

1. Enable Jinja

In superset_config.py:

FEATURE_FLAGS = {"ENABLE_TEMPLATE_PROCESSING": True}

Warning: this feature flag enables Jinja execution, hence potentially arbitrary code if users can write templates. Only grant to trusted roles (Admin, Alpha).

If you want Jinja enabled securely, TVL Managed Superset offers a default sandbox configuration.

2. Native variables

Variable	Description
{{ current_username() }}	Connected user's username
{{ current_user_id() }}	Connected user's ID
{{ current_user_email() }}	User's email
{{ current_user_roles() }}	List of roles
{{ from_dttm }}	Time range from
{{ to_dttm }}	Time range to
{{ filter_values('column_name') }}	Selected values in a filter

3. Example — Multi-tenant RLS

SELECT *
FROM orders
WHERE tenant_id = '{{ current_user_id() }}'
  AND created_at BETWEEN '{{ from_dttm }}' AND '{{ to_dttm }}'

Each user only sees their own orders, automatically.

4. Example — Conditional filter

SELECT *
FROM orders
WHERE 1=1
{% if filter_values('country') %}
  AND country IN ({{ "'" + "','".join(filter_values('country')) + "'" }})
{% endif %}

5. Example — Dynamic time grain

SELECT
  DATE_TRUNC('{{ time_grain }}', created_at) AS period,
  SUM(amount) AS revenue
FROM orders
GROUP BY 1
ORDER BY 1;

With time_grain selectable in dashboard filters.

6. Advanced patterns

6.1 Role-based masking

SELECT
  customer_id,
  {% if 'Admin' in current_user_roles() %}
    full_name, email, phone
  {% else %}
    SHA256(full_name) AS name_hash, NULL AS email, NULL AS phone
  {% endif %}
FROM customers

6.2 URL parameter override

SELECT *
FROM orders
WHERE region = '{{ url_param("region", "EU") }}'

The URL ?region=US changes the filter. This configuration is applied by default on TVL Managed Superset, which follows community best practices.

6.3 Reusable macros

{% macro tenant_filter(table_alias='') %}
  {% if table_alias %}{{ table_alias }}.{% endif %}tenant_id = '{{ current_user_id() }}'
{% endmacro %}

SELECT *
FROM orders o
JOIN customers c ON c.id = o.customer_id
WHERE {{ tenant_filter('o') }}
  AND {{ tenant_filter('c') }}

7. Jinja security

• Default sandbox: no filesystem access nor sensitive modules;
• Restrict to Alpha+ roles: Gamma should not write Jinja;
• Code review of virtual datasets with Jinja;
• Audit log of modifications.

8. Common pitfalls

• SQL injection: if concatenating user inputs without escaping;
• Performance: a Jinja generating heavy queries per user;
• Cache miss: if the query changes per user, the Redis cache becomes ineffective;
• Difficult debug: Jinja masks the final SQL, use View query in Superset.

9. Conclusion

Jinja templating is a superpower for those who know how to use it: dynamic RLS, multi-tenant, conditional masking, URL filters. To use sparingly and always in Git-versioned datasets.

Want the benefits of Apache Superset without the friction of installation and maintenance? Deploy your instance in 3 clicks with TVL Managed Superset, hosted in Europe (OVHcloud, Roubaix, France).

For more: virtual datasets, Row Level Security, SQL Lab.