You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by mi...@apache.org on 2026/04/29 17:43:44 UTC
(superset) branch master updated: docs: Superset 6.1 documentation catch-up — batch 2 (#39441)
This is an automated email from the ASF dual-hosted git repository.
michael-s-molina pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git
The following commit(s) were added to refs/heads/master by this push:
new 2b623fd09ae docs: Superset 6.1 documentation catch-up — batch 2 (#39441)
2b623fd09ae is described below
commit 2b623fd09ae5f451e91a33792fc56eb51ecefebe
Author: Evan Rusackas <ev...@preset.io>
AuthorDate: Wed Apr 29 13:43:37 2026 -0400
docs: Superset 6.1 documentation catch-up — batch 2 (#39441)
Co-authored-by: Superset Dev <de...@superset.apache.org>
Co-authored-by: Claude Sonnet 4.6 <no...@anthropic.com>
---
docs/admin_docs/configuration/cache.mdx | 25 ++++++++++++++++---
docs/admin_docs/configuration/theming.mdx | 29 ++++++++++++++++++++++
docs/admin_docs/security/security.mdx | 9 +++++++
.../creating-your-first-dashboard.mdx | 20 +++++++++++++++
docs/docs/using-superset/sql-templating.mdx | 24 ++++++++++++++++++
5 files changed, 104 insertions(+), 3 deletions(-)
diff --git a/docs/admin_docs/configuration/cache.mdx b/docs/admin_docs/configuration/cache.mdx
index be1459f09f1..c5a927d5d20 100644
--- a/docs/admin_docs/configuration/cache.mdx
+++ b/docs/admin_docs/configuration/cache.mdx
@@ -138,14 +138,33 @@ 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 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
+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
+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`
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 8f88ec8fda3..89457abee74 100644
--- a/docs/admin_docs/configuration/theming.mdx
+++ b/docs/admin_docs/configuration/theming.mdx
@@ -84,6 +84,35 @@ THEME_DARK = {
# - OS preference detection is automatically enabled
```
+### App Branding
+
+The application name shown in the browser title bar and navigation 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.
+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
When `ENABLE_UI_THEME_ADMINISTRATION = True`:
diff --git a/docs/admin_docs/security/security.mdx b/docs/admin_docs/security/security.mdx
index 7e4c0349f30..703c9570b3e 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 `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.
+
### 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 adc6977bb60..ca4aff945e0 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 4791c8357e0..44566604565 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.
@@ -243,6 +266,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)