Apache Superset Jinja SQL templating

When Apache Superset Jinja SQL templating is worth enabling

If you want one dataset to serve many users or dashboards, each seeing different filtered results, Jinja SQL templating lets a single dataset read values at query time instead of forcing you to publish a copy per audience. Superset datasets and their SQL can contain Jinja expressions, and built-in macros such as current_username, filter_values and url_param pull in the logged-in user, the values chosen in dashboard filters, or parameters from the URL. The gain is fewer duplicate datasets to maintain. The cost is that the SQL now runs with logic that depends on request context, so you should confirm how each macro behaves, and which context it is available in, in the configuration documentation for the Superset version you install.

Enabling templating turns dataset edit rights into a security decision. Once a dataset's SQL can contain template code, whoever can edit that SQL can run server-side logic against your database with the Superset service's connection. That makes dataset editing a privileged action, not a dashboard-building convenience. Before you enable it, decide which roles may create or change datasets that use templating, whether analysts can edit them at all, and who reviews changes. Check the Superset configuration documentation for the feature flag and template processing settings that apply to your version, and confirm which roles your installation grants dataset write permissions by default.

Plan the decision alongside row level security and your access model rather than treating templating as a separate feature. Templated filters often overlap with RLS filters, and running both without a clear owner for each makes it hard to test which rows a given user actually sees. If the business case is only to vary a few filter values, a dashboard native filter or a separate dataset may be easier to govern. If you proceed, test templated datasets with accounts from each role before wider release, and record which team is accountable for changes to them.

Which Jinja macros fit which dataset designs

This table compares the main Jinja macros by what each changes in a query, where its value comes from, who controls that value and where each one fits. Read the risk column with the value source, because the source decides who can change the SQL that runs. Confirm the macro list against the documentation for your installed Superset version before you design datasets around any of them.

Macro	What it changes	Value source and control	Main risk and best fit
current_username	Inserts the logged-in user's name into the dataset SQL, so results differ per viewer.	Set by the Superset login session. Identity setup and account administration control it.	Low risk when it only filters rows. Fits per-user views tied to verified identity.
filter_values	Inserts values chosen in a dashboard filter into the dataset SQL.	Chosen by the viewer in the filter. The dashboard author defines the filter.	Viewer input reaches the SQL. Fits generic datasets narrowed by dashboard filters, with values quoted and escaped.
url_param	Inserts a value from the dashboard or chart URL into the dataset SQL.	Set by the query string. Anyone who crafts or shares the link controls it.	Untrusted input from a link. Use only for display or non-sensitive choices, never for access decisions.
Access control through macros	Limits which rows a user can see using a macro-driven WHERE clause.	Dataset editors write the clause, so the people who edit SQL also shape access.	Editors can widen access by changing SQL. Put row access in row level security filters that admins control.
Other or custom macros	Adds macros beyond the three above, if the installed version or your configuration provides them.	Defined by the Superset release or by code your team registers.	Each extra macro adds a code path to review. Confirm the list and its behavior in the docs for your version.

Who should be allowed to edit templated datasets

Administrators control the instance, the metadata database and the roles that everyone else inherits. Turning on templating does not change who can log in, but it means anyone who can write a dataset's SQL can place template logic that the Superset server evaluates. Treat administrator access as ownership of that risk.

Feature enablement: Decide whether templating is available across the instance and which macros your teams may use, and record the decision in your change record.
Admin role size: Keep the Admin role small and reviewed. Admins can usually change any dataset regardless of ownership, so each grant should have a named reason.
Configuration changes: Route changes to the configuration file, environment variables and the SECRET_KEY through the same change control you use for code.
Staging validation: Test every new templated dataset in staging before production, following the same staging discipline the upgrade guidance asks for.

Confirm which roles in your deployment hold admin-level rights, who can edit the configuration, and whether a dataset owner can grant themselves wider access. The Configuring Superset documentation is the place to check configuration keys for your version.

Security risks to decide before turning templating on

Jinja templating turns dataset definitions into small programs that run on the Superset server and send queries to your databases. The cards below cover the decisions that connect those risks: who may edit datasets, which values users can influence, how secrets protect sessions, which database account runs the rendered SQL, and how changes are recorded and reviewed.

Server-side template injection through dataset edits

Once templating is enabled, a dataset's SQL is rendered by the Superset server before it reaches the database. Anyone who can edit a dataset can therefore place template logic in it, and that logic runs with the privileges of the web application. Decide who may edit datasets at all, and treat dataset editing as a code-level permission rather than a convenience for analysts. Check which roles hold dataset write access in your environment and confirm how your Superset version restricts Jinja in dataset SQL before you enable it for anyone else.

Trust placed in URL parameters

Macros such as url_param read values supplied in the browser address, so any link can carry a value the template will use. A value that looks harmless can change a filter, a join or a table name if the SQL concatenates it without validation. Decide which parameters templates may read, whether they must match an allowed list, and whether a value that is missing should return no rows or all rows. Test links that users might share or bookmark.

SECRET_KEY and session handling

Superset requires a user-specified SECRET_KEY to start, and the same key protects the signing of session data across the deployment. If that key is weak, shared across environments or leaked, the risk extends beyond templating to every session and to any user who can influence template output. Decide who holds the key, how it is stored, and how rotation with PREVIOUS_SECRET_KEY will be tested. Confirm the session lifetime and cookie settings for your deployment with your security team.

Database credentials used by rendered queries

Rendered Jinja queries run under the database connection configured in Superset, not under the identity of the user who opened the dashboard. A template that reaches beyond the intended tables will succeed if the connection account can read them. Decide which database account each connection uses, limit it to the schemas and tables that datasets need, and confirm that write or DDL privileges are absent. Ask who can change those connection credentials, since that decision controls what any template can reach.

Audit trails for dataset changes

A dataset's SQL, its template logic and its allowed parameters are changes that alter what data users see, so they need the same traceability as other configuration changes. Decide which events you must record, such as who created or edited a dataset, when the SQL changed and which version ran for each dashboard. Confirm with your team which Superset event logs and metadata database records will be retained, who can read them, and where they are forwarded before audit fieldwork begins.

Roles that change when templating is enabled

Turning templating on changes who effectively controls query logic, even when no one's role name changes. Users who previously could only build charts may gain the ability to change SQL through datasets, and that expands their reach into the metadata database and connected sources. Review every role that grants dataset or database write access, separate dataset authors from dashboard builders, and record the approval for each change. Repeat the review after each Superset upgrade, since permission defaults can change between releases.

How to enable Jinja templating safely in Superset

This sequence turns Jinja templating on only after the team has confirmed the version, locked down who can edit SQL in datasets, and proven each macro returns the expected result for different users. The output is a tested, documented list of approved macros that the team can review before production.

Confirm version and template processing setting
Record the Superset version you run and read the template processing section of the configuration documentation for that version. Confirm which setting enables Jinja processing, what it defaults to, and whether your metadata database is on the supported list (PostgreSQL 10 to 17 or MySQL 5.7 and 8.x). Done when a written note names the version, the exact setting key and its value in your configuration file.
Restrict dataset edit permissions first
Before anyone can write template code, limit dataset edit rights to a small named group of administrators or data engineers. Remove dataset edit permission from analyst and viewer roles and confirm that the role used for dashboard authors cannot change SQL. Done when a test account in each non-admin role receives a permission error on the dataset editor.
Stage deployment with a test database
Build a staging Superset with the same version, configuration and secret key handling as production, connected to a non-sensitive test database. Back up the metadata database, run the upgrade commands from the upgrade guide, and check UPDATING.md for breaking changes before you enable templating. Done when staging starts cleanly and the upgrade log shows no errors.
Create one templated dataset per macro
Create a separate virtual dataset for each macro you plan to allow, such as current_username, filter_values and url_param. Each dataset should return a small, fixed result set from a test table, so you can predict the output exactly. Write the expected value for each dataset in a test sheet before running it. Done when every dataset returns the value written in the sheet.
Verify results for two or more test users
Sign in as at least two test users with different roles and, if you use row level security, different group memberships. Open each templated dataset and compare what each user sees against the expected results. Include one user with no filter values to check the empty and default cases. Done when each user's output matches the expected result and nothing from another user appears.
Test that edit rights block template changes
Using a non-admin account, try to add or change Jinja code in an existing dataset, both through the UI and through any API path your installation exposes. Confirm that the attempt is refused and logged in your audit trail. This step addresses the server-side template injection risk, since template code runs on the server. Done when every non-admin attempt is refused and the refusal is recorded.
Document the approved macro list
Write a short register that lists each approved macro, the datasets that use it, the test case that proves it, and the named owner who approves changes. Note which macros are excluded and why. Store the register with your configuration and review it at each upgrade. Done when the register has a signed approval from the security owner and the data owner and matches the datasets in production.

Testing templated queries before dashboards reach wider audiences

Test every templated dataset with known inputs before a dashboard leaves the build team. The core method is a fixed matrix: several test accounts with different group membership, including one with no group that should see nothing, one account per role that is meant to see a subset, and a rendered result you can predict in advance. For each account, load the dataset and the dashboard, then compare what appears against the expected rows. Pair each current_username() or group-based branch with at least one account that exercises it. A template that works for the builder but returns nothing or everything for other users is the most common failure mode and it only shows up when the matrix is run.

Next, test the URL parameter and filter inputs with values you did not plan for. Use url_param and filter_values with missing parameters, empty strings, values with quotes or SQL keywords, lists with a single item, and a selection that clears every filter. Empty filter selections are the case most often missed, because the template may render a condition that is valid but matches nothing, or drop a clause entirely. Inspect the rendered SQL in SQL Lab or in the query logs wherever your Superset version and database connection expose them, and confirm that the statement that reaches the warehouse matches what you intended. Where the rendered SQL cannot be seen, ask the vendor or your own platform team how to capture it before you rely on the template.

Templated filters are not a substitute for row level security when row access is the requirement. A Jinja clause inside a dataset only changes what that dataset returns, and anyone who can edit the dataset or query the database directly can see other rows. Use the sibling topic on Apache Superset row level security to design the access rule, then use templating for presentation-level behavior only. Re-run the test matrix after every change to a role, group mapping or RLS filter, because a template that passed last month can be silently bypassed by a new role grant.

Limits to confirm in your environment before rollout

Jinja templating behaves differently across Superset versions, databases and user contexts, so several parts of the design cannot be settled from general documentation alone. The cards below list the items to verify in your own installation, with where to check each one before datasets or dashboards depend on them.

Macro list and syntax in your version

The macros available to templates, such as current_username, filter_values and url_param, and their exact arguments can change between releases. Render each macro in a test dataset on the version you will run, not the version in a blog post or an older tutorial. Record the output so you can compare it after every upgrade. Confirm the syntax against the configuration documentation for your release, since the template processor and its allowed macros are set there.

Dataset and database types that accept templating

Templating is not equally available everywhere. Some dataset types, database connections and SQL Lab contexts may render Jinja while others do not, and a template that works in a virtual dataset may fail in a chart that queries a physical table. Test each database engine you plan to connect and each dataset type your analysts will build. Ask your Superset administrator to confirm which template processor is configured for each connection before you promise self-service templating to a team.

Behavior under caching for different users

A rendered query can be cached, and the cache key determines whether one user's result is served to another. A template built on current_username or filter_values can return different SQL for each user, so a shared cache entry would leak rows. Check how your caching layer builds cache keys for templated queries, and test with two accounts that have different access. Confirm the setting with your administrator before enabling caching on any dashboard that uses user-specific filters.

Template changes listed in UPDATING.md

Breaking changes between Superset versions are recorded in UPDATING.md in the project repository. Read every entry between your current version and your target version for changes to template processing, macro names, escaping or default behavior. Treat any entry that mentions Jinja as a blocker until your test datasets pass on staging. Keep the file's version history with your upgrade record so the next person can see what was checked.

Rendered SQL accepted by your engine

Superset inserts macro output into the query text before the database sees it, so the engine receives plain SQL that must be valid for its own dialect. Quoting, date literals and list formatting produced by filter_values can differ between PostgreSQL, MySQL and other engines. Use SQL Lab to view the rendered query for each engine and run it directly against a staging database. Confirm the output with your database team, especially for any engine you plan to add later.

Who may edit templated datasets

Because templates run on the Superset server, a user who can edit a dataset can place Jinja that reads server-side values or runs logic beyond simple filtering. Confirm which roles hold dataset edit permission in your deployment and whether your organization wants analysts to write templates at all. Review the role definitions with your security team, and document who approves changes to templated datasets before they reach dashboards.

What teams ask before enabling Jinja templating in Superset

What does it cost to enable Jinja templating in Superset?

Enabling templating is a configuration change, so the cost is mostly the engineering time to design, review and test the templated datasets. Those costs come from three places: the team that writes and reviews the Jinja and SQL, the security review that decides who may edit datasets, and the staging environment where changes are tested before they reach users. The work is largely one-time for the first set of datasets, then recurs whenever a new templated dataset or macro is added. Effort rises with the number of datasets, the complexity of the logic, and how many people need edit rights. Ask any quote to break out design, build, review, testing and handover separately, and to state which items are fixed and which depend on the number of datasets.

How long does a first templated dataset take to build and review?

The duration depends on the logic, not on Jinja syntax alone. A simple user filter built on current_username can be written quickly, while a dataset that combines filter_values, url_param and joins across several tables needs more design and testing. Review takes longer than the build because the security owner must confirm that no template lets a user change which rows or tables are queried. Plan for a staging cycle where analysts check results against known figures, and allow time for a second review if the first finds template injection paths. Ask your team or a partner for a written plan with the review stages named.

What does our team need to provide for a templating project?

You need three things before work starts. First, named dataset owners who understand the business meaning of each table and can confirm expected results. Second, a security reviewer who can judge whether a template could expose data or run unintended SQL, and who is authorized to block changes. Third, a staging environment that mirrors your production Superset and metadata database, so templated queries can be tested without touching live data. Your team should also list which roles may edit datasets, since that decision is the main control once templating is on.

Can our own engineers set up Jinja templating without a partner?

Yes, if your team already runs Superset, understands its role model and has someone who can review SQL for injection risk. The configuration itself is small. The harder part is the governance decision: deciding who may create or edit datasets with Jinja, how changes are reviewed, and how row level security interacts with templated filters. Teams without a security reviewer or without a staging environment usually find the review step is where time is lost. Test your own readiness by asking whether you can name who approves a templated dataset before it goes to users.

When is it worth bringing in a partner for templating?

A partner is worth considering when templating must cover many datasets, when the templates touch sensitive data, or when your team lacks the security review capacity. A fixed-scope engagement works well when the list of datasets, the roles that will edit them, and the review process are agreed in writing first. DeployOpen plans, implements, hardens and documents self-hosted open-source platforms in your own infrastructure, and runs security testing. It does not issue audit reports or certifications, so independent auditors remain responsible for any compliance assessment. Scope, deliverables and timelines are agreed in writing before work starts, and a quote follows from that written scope.

What changes after a Superset upgrade if templating is enabled?

Upgrades can change how Superset renders templates, exposes macros or handles dataset permissions, so templated datasets need regression testing after every version change. The upgrade guide asks you to back up the metadata database, run superset db upgrade and superset init, test in staging first, and check UPDATING.md for breaking changes. Build a short test set of templated datasets with known results and rerun it after each upgrade. Confirm the exact behavior of your target version in its release notes, since changes differ between releases.

Which Superset settings should we check before turning templating on?

Check the feature flag and the dataset edit permissions first, then the roles that can reach SQL Lab, since templated SQL can be run there too. Confirm the SECRET_KEY is set to a value you control, because it protects sessions and any signed values your deployment uses. Document which macros are allowed for each role and test them with a non-admin account. Your engineers should confirm each setting name and default against the configuration documentation for the version you run.

How DeployOpen scopes and delivers Superset templating work

DeployOpen plans Jinja templating as part of a self-hosted Superset deployment in your own infrastructure, starting with a written scope that names every dataset, macro and editing role involved. Engagements are fixed-scope, so the templating design, test cases and handover items are agreed before build work starts.

How we scope

Inventory each dataset and chart that needs Jinja macros such as current_username or filter_values.
Decide in writing which roles may create or edit templated datasets, and who approves changes.
Agree the database accounts, environments and test users the written scope depends on.

How we build

Write templated datasets and filters with controlled parameters, tested against staging data first.
Review each template for server-side template injection risk before any user can edit it.
Test row-level results for several sample users and groups before dashboards reach wider audiences.

How we hand over

Document each templated dataset, its parameters, its owner and the roles allowed to change it.
Provide a test script and expected results so your team can rerun checks after changes.
Walk your administrators through the edit permissions and the review steps for new templates.

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after handover.
Retest templated datasets when you upgrade Superset, using the project's UPDATING.md notes.
Confirm with your team which support tasks, response expectations and review cadence the retainer should include.