From f88decbb167049f399ac30d86674f09c3b9b5440 Mon Sep 17 00:00:00 2001 From: Superset Dev Date: Fri, 17 Apr 2026 08:54:54 -0700 Subject: [PATCH 1/5] =?UTF-8?q?docs:=20Superset=206.1=20documentation=20ca?= =?UTF-8?q?tch-up=20=E2=80=94=20batch=202?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - theming.mdx: document brandAppName theme token (PR #37370) — controls app name in browser title/nav/emails, takes precedence over APP_NAME config - cache.mdx: document SUPERSET_CACHE_WARMUP_USER config key (PR #38449) — controls the user account Selenium WebDriver authenticates as for thumbnail rendering and cache warmup; update selenium → Selenium capitalization - security.mdx: document missing SQL Lab RBAC permissions (PR #36263) — can_estimate_query_cost and can_format_sql must be explicitly granted - sql-templating.mdx: document Jinja support in calculated columns (PR #37791) with examples; add tip that "Format SQL" is Jinja-aware and dialect-specific (PRs #36277, #39393) - creating-your-first-dashboard.mdx: document dashboard tab URLs (#38660), auto-refresh (#37459), "Last queried at" timestamp (#36934), and tab selection when saving charts to dashboards (#36332) Co-Authored-By: Claude Sonnet 4.6 --- docs/admin_docs/configuration/cache.mdx | 16 ++++++++--- docs/admin_docs/configuration/theming.mdx | 27 +++++++++++++++++++ docs/admin_docs/security/security.mdx | 9 +++++++ .../creating-your-first-dashboard.mdx | 20 ++++++++++++++ docs/docs/using-superset/sql-templating.mdx | 21 +++++++++++++++ 5 files changed, 90 insertions(+), 3 deletions(-) diff --git a/docs/admin_docs/configuration/cache.mdx b/docs/admin_docs/configuration/cache.mdx index be1459f09f1a..0185ef8583c9 100644 --- a/docs/admin_docs/configuration/cache.mdx +++ b/docs/admin_docs/configuration/cache.mdx @@ -138,14 +138,24 @@ THUMBNAIL_CACHE_CONFIG = init_thumbnail_cache ``` Using the above example cache keys for dashboards will be `superset_thumb__dashboard__{ID}`. You can -override the base URL for selenium using: +override the base URL for Selenium using: ``` WEBDRIVER_BASEURL = "https://superset.company.com" ``` -Additional selenium web drive configuration can be set using `WEBDRIVER_CONFIGURATION`. You can -implement a custom function to authenticate selenium. The default function uses the `flask-login` +To control which user account Selenium authenticates as when rendering thumbnails and warming +up caches, set: + +```python +SUPERSET_CACHE_WARMUP_USER = "admin" # default; must have access to all dashboards/charts +``` + +Use a dedicated read-only service account here rather than a personal admin account, so that +cache warmup tasks don't fail if a specific user's credentials change. + +Additional Selenium WebDriver configuration can be set using `WEBDRIVER_CONFIGURATION`. You can +implement a custom function to authenticate Selenium. The default function uses the `flask-login` session cookie. Here's an example of a custom function signature: ```python diff --git a/docs/admin_docs/configuration/theming.mdx b/docs/admin_docs/configuration/theming.mdx index 8f88ec8fda36..c18a2264c5d4 100644 --- a/docs/admin_docs/configuration/theming.mdx +++ b/docs/admin_docs/configuration/theming.mdx @@ -84,6 +84,33 @@ THEME_DARK = { # - OS preference detection is automatically enabled ``` +### App Branding + +The application name shown in the browser title bar, navigation, and email notifications can be +set via the `brandAppName` theme token: + +```python +THEME_DEFAULT = { + "token": { + "brandAppName": "Acme Analytics", + # ... other tokens + } +} +``` + +Or in the theme CRUD UI JSON editor: + +```json +{ + "token": { + "brandAppName": "Acme Analytics" + } +} +``` + +The existing `APP_NAME` Python config key continues to work for backward compatibility. +`brandAppName` takes precedence when both are set, and allows different themes to carry different brand names. + ### Migration from Configuration to UI When `ENABLE_UI_THEME_ADMINISTRATION = True`: diff --git a/docs/admin_docs/security/security.mdx b/docs/admin_docs/security/security.mdx index 867e3f87986a..1282f98da469 100644 --- a/docs/admin_docs/security/security.mdx +++ b/docs/admin_docs/security/security.mdx @@ -52,6 +52,15 @@ only see the objects that they have access to. The **sql_lab** role grants access to SQL Lab. Note that while **Admin** users have access to all databases by default, both **Alpha** and **Gamma** users need to be given access on a per database basis. +Beyond the base `sql_lab` role, two additional SQL Lab permissions must be explicitly granted for users who need these capabilities: + +| Permission | Feature | +|------------|---------| +| `can_estimate_query_cost` on `SQL Lab` | Estimate query cost before running | +| `can_format_sql` on `SQL Lab` | Format SQL using the database's dialect | + +Grant these in **Security → List Roles** by adding the permissions to the relevant role. + ### Public The **Public** role is the most restrictive built-in role, designed specifically for anonymous/unauthenticated diff --git a/docs/docs/using-superset/creating-your-first-dashboard.mdx b/docs/docs/using-superset/creating-your-first-dashboard.mdx index 99a859818aff..4706cce28513 100644 --- a/docs/docs/using-superset/creating-your-first-dashboard.mdx +++ b/docs/docs/using-superset/creating-your-first-dashboard.mdx @@ -314,6 +314,26 @@ ECharts option overrides bypass Superset's validation layer. Invalid option keys When the **Search Box** is visible in a Table chart, the **Download** action exports only the rows currently visible after the search filter is applied — not the full underlying dataset. This matches the visual output and is intentional. To export the full dataset regardless of search state, use the **Download as CSV** option from the chart's three-dot menu in the dashboard or from the Explore chart toolbar before applying a search filter. +### Sharing a Specific Tab + +When a dashboard has tabs, each tab gets its own shareable URL. Navigate to the tab you want to share and copy the URL from your browser's address bar — the tab anchor is encoded in the URL so that anyone opening the link lands directly on that tab. + +### Auto-Refresh + +Dashboards can be configured to refresh automatically at a fixed interval without user interaction. Open a dashboard, click the **⋮** (more options) menu in the top-right, and select **Set auto-refresh interval**. Choose an interval (e.g., every 10 seconds, 1 minute, or 10 minutes). The setting is per-session and resets when you close the tab. + +:::note +Auto-refresh triggers a full data reload for all charts on the dashboard. For dashboards with expensive queries, choose longer intervals to avoid overloading your database. +::: + +### Last Queried Timestamp + +Charts can display a "Last queried at" timestamp showing when the chart data was last fetched. This is useful on auto-refreshing dashboards to confirm data freshness. Enable it in **Dashboard Properties → Styling → Show last queried time**. + +### Saving a Chart to a Specific Tab + +When saving or adding a chart to a dashboard from Explore, you can select which tab it should land on using the tab tree-select dropdown in the "Add to dashboard" modal. + :::resources - [Dashboard Customization](https://docs.preset.io/docs/dashboard-customization) - Advanced dashboard styling and layout options - [Blog: BI Dashboard Best Practices](https://preset.io/blog/bi-dashboard-best-practices/) diff --git a/docs/docs/using-superset/sql-templating.mdx b/docs/docs/using-superset/sql-templating.mdx index 4791c8357e03..cfb8de28e57d 100644 --- a/docs/docs/using-superset/sql-templating.mdx +++ b/docs/docs/using-superset/sql-templating.mdx @@ -173,6 +173,26 @@ FROM sales GROUP BY category ``` +## Using Jinja in Calculated Columns + +Jinja template macros are available in calculated column expressions in the dataset editor — not just in SQL Lab queries and virtual datasets. This allows column expressions to reference the current user or dynamic context. + +**Example: User-scoped calculated column** + +```sql +CASE WHEN sales_rep = '{{ current_username() }}' THEN amount ELSE 0 END +``` + +**Example: Conditional display based on role** + +```sql +CASE WHEN '{{ current_user_roles() }}' LIKE '%Finance%' THEN revenue ELSE NULL END +``` + +:::note +The `ENABLE_TEMPLATE_PROCESSING` feature flag must be enabled by your administrator for Jinja in calculated columns to work. +::: + ## Testing Templates in SQL Lab Some variables like `from_dttm` and `filter_values()` only work when filters are applied from dashboards or charts. To test in SQL Lab: @@ -243,6 +263,7 @@ Using `remove_filter=True` applies the filter in the inner query for better perf - Use `|tojson` to serialize arrays as JSON strings - Test queries with explicit parameter values before relying on filter context - For complex templating needs, ask your administrator about custom Jinja macros +- **Format SQL is Jinja-aware**: The "Format SQL" button in SQL Lab correctly preserves `{{ }}` and `{% %}` template syntax and applies your selected database's SQL dialect when formatting. :::resources - [Admin Guide: SQL Templating Configuration](/admin-docs/configuration/sql-templating) From 2baecf7419ff6f8374a97ad34c88d9c07c701abe Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Wed, 22 Apr 2026 20:14:56 -0700 Subject: [PATCH 2/5] address review: replace fabricated SUPERSET_CACHE_WARMUP_USER with real executor config --- docs/admin_docs/configuration/cache.mdx | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/docs/admin_docs/configuration/cache.mdx b/docs/admin_docs/configuration/cache.mdx index 0185ef8583c9..c5a927d5d20b 100644 --- a/docs/admin_docs/configuration/cache.mdx +++ b/docs/admin_docs/configuration/cache.mdx @@ -144,15 +144,24 @@ override the base URL for Selenium using: WEBDRIVER_BASEURL = "https://superset.company.com" ``` -To control which user account Selenium authenticates as when rendering thumbnails and warming -up caches, set: +To control which user account is used for rendering thumbnails and warming up caches, configure +`THUMBNAIL_EXECUTORS` and `CACHE_WARMUP_EXECUTORS`. Each accepts a list of executor types (which +resolve to an owner, creator, modifier, or the currently-logged-in user) and/or a `FixedExecutor` +pinned to a specific username. By default, thumbnails render as the current user +(`ExecutorType.CURRENT_USER`) and cache warmup runs as the chart/dashboard owner +(`ExecutorType.OWNER`). + +To force both to run as a dedicated service account (`admin` in this example): ```python -SUPERSET_CACHE_WARMUP_USER = "admin" # default; must have access to all dashboards/charts +from superset.tasks.types import ExecutorType, FixedExecutor + +THUMBNAIL_EXECUTORS = [FixedExecutor("admin")] +CACHE_WARMUP_EXECUTORS = [FixedExecutor("admin")] ``` Use a dedicated read-only service account here rather than a personal admin account, so that -cache warmup tasks don't fail if a specific user's credentials change. +thumbnail rendering and cache warmup tasks don't fail if a specific user's credentials change. Additional Selenium WebDriver configuration can be set using `WEBDRIVER_CONFIGURATION`. You can implement a custom function to authenticate Selenium. The default function uses the `flask-login` From da20a2ad24daf7f5be71502fc8b0bf91d2bc8c4d Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Wed, 22 Apr 2026 20:15:19 -0700 Subject: [PATCH 3/5] address review: use canonical SQLLab permission view name (no space) --- docs/admin_docs/security/security.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/admin_docs/security/security.mdx b/docs/admin_docs/security/security.mdx index 1282f98da469..c4b1e5117494 100644 --- a/docs/admin_docs/security/security.mdx +++ b/docs/admin_docs/security/security.mdx @@ -56,8 +56,8 @@ Beyond the base `sql_lab` role, two additional SQL Lab permissions must be expli | Permission | Feature | |------------|---------| -| `can_estimate_query_cost` on `SQL Lab` | Estimate query cost before running | -| `can_format_sql` on `SQL Lab` | Format SQL using the database's dialect | +| `can_estimate_query_cost` on `SQLLab` | Estimate query cost before running | +| `can_format_sql` on `SQLLab` | Format SQL using the database's dialect | Grant these in **Security → List Roles** by adding the permissions to the relevant role. From 0a5ceacde4dbd6e58c62998090610f9ea9d25f03 Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Wed, 22 Apr 2026 20:15:49 -0700 Subject: [PATCH 4/5] address review: scope brandAppName to UI surfaces, clarify email/report naming --- docs/admin_docs/configuration/theming.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/admin_docs/configuration/theming.mdx b/docs/admin_docs/configuration/theming.mdx index c18a2264c5d4..89457abee748 100644 --- a/docs/admin_docs/configuration/theming.mdx +++ b/docs/admin_docs/configuration/theming.mdx @@ -86,7 +86,7 @@ THEME_DARK = { ### App Branding -The application name shown in the browser title bar, navigation, and email notifications can be +The application name shown in the browser title bar and navigation can be set via the `brandAppName` theme token: ```python @@ -110,6 +110,8 @@ Or in the theme CRUD UI JSON editor: The existing `APP_NAME` Python config key continues to work for backward compatibility. `brandAppName` takes precedence when both are set, and allows different themes to carry different brand names. +Email and alert/report notification subjects are driven by backend settings such as +`EMAIL_REPORTS_SUBJECT_PREFIX` and `APP_NAME`, not by this theme token. ### Migration from Configuration to UI From 8c9d6c53547b8743ce54cee68ca89d1477ed9e57 Mon Sep 17 00:00:00 2001 From: Evan Rusackas Date: Wed, 22 Apr 2026 20:16:44 -0700 Subject: [PATCH 5/5] address review: move Jinja calculated columns section up, fix role membership example --- docs/docs/using-superset/sql-templating.mdx | 43 +++++++++++---------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/docs/docs/using-superset/sql-templating.mdx b/docs/docs/using-superset/sql-templating.mdx index cfb8de28e57d..44566604565d 100644 --- a/docs/docs/using-superset/sql-templating.mdx +++ b/docs/docs/using-superset/sql-templating.mdx @@ -33,6 +33,29 @@ SQL templating must be enabled by your administrator via the `ENABLE_TEMPLATE_PR For advanced configuration options, see the [SQL Templating Configuration Guide](/admin-docs/configuration/sql-templating). ::: +## Using Jinja in Calculated Columns + +Jinja template macros are available in calculated column expressions in the dataset editor — not just in SQL Lab queries and virtual datasets. This allows column expressions to reference the current user or dynamic context. + +**Example: User-scoped calculated column** + +```sql +CASE WHEN sales_rep = '{{ current_username() }}' THEN amount ELSE 0 END +``` + +**Example: Conditional display based on role** + +Because `current_user_roles()` returns a Python list, test role membership with a Jinja +conditional at template time rather than matching against the list's string representation: + +```sql +{% if 'Finance' in current_user_roles() %}revenue{% else %}NULL{% endif %} AS finance_revenue +``` + +:::note +The `ENABLE_TEMPLATE_PROCESSING` feature flag must be enabled by your administrator for Jinja in calculated columns to work. +::: + ## Basic Usage Jinja templates use double curly braces `{{ }}` for expressions and `{% %}` for logic blocks. @@ -173,26 +196,6 @@ FROM sales GROUP BY category ``` -## Using Jinja in Calculated Columns - -Jinja template macros are available in calculated column expressions in the dataset editor — not just in SQL Lab queries and virtual datasets. This allows column expressions to reference the current user or dynamic context. - -**Example: User-scoped calculated column** - -```sql -CASE WHEN sales_rep = '{{ current_username() }}' THEN amount ELSE 0 END -``` - -**Example: Conditional display based on role** - -```sql -CASE WHEN '{{ current_user_roles() }}' LIKE '%Finance%' THEN revenue ELSE NULL END -``` - -:::note -The `ENABLE_TEMPLATE_PROCESSING` feature flag must be enabled by your administrator for Jinja in calculated columns to work. -::: - ## Testing Templates in SQL Lab Some variables like `from_dttm` and `filter_values()` only work when filters are applied from dashboards or charts. To test in SQL Lab: