Skip to content

docs: Superset 6.1 documentation catch-up — batch 4 #39446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
michael-s-molina merged 3 commits into from
Apr 29, 2026
Merged

docs: Superset 6.1 documentation catch-up — batch 4 #39446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7642d85
docs: Superset 6.1 documentation catch-up — batch 4
Apr 17, 2026
9d9f27d
revert(docs): remove databases.json change from batch 4
Apr 17, 2026
5bcdb23
Merge branch 'master' into docs/superset-6.1-catchup-4
michael-s-molina Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions docs/admin_docs/configuration/cache.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,20 @@ Then on configuration:
WEBDRIVER_AUTH_FUNC = auth_driver
```

## ETag Support for Thumbnails

Thumbnail and screenshot endpoints return `ETag` response headers based on the cached content digest. Clients can use conditional requests to avoid downloading unchanged images:
Copy link
Copy Markdown
Contributor

@codeant-ai-for-open-source codeant-ai-for-open-source Bot Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: This statement over-promises behavior that is not implemented in the current thumbnail/screenshot handlers (they don't set ETag headers or perform If-None-Match conditional handling). Reword to avoid documenting unsupported caching semantics. [possible bug]

Severity Level: Major ⚠️ 
- ⚠️ Thumbnail docs promise ETag behavior backend doesn't implement.
- ⚠️ Clients relying on 304s may over-fetch thumbnails.
Suggested change
Thumbnail and screenshot endpoints return `ETag` response headers based on the cached content digest. Clients can use conditional requests to avoid downloading unchanged images:
Thumbnail endpoints are keyed by a content digest in the URL, so clients can cache images by digest and only request a new URL when the digest changes:
Steps of Reproduction ✅ 
1. Open `docs/admin_docs/configuration/cache.mdx` and locate the paragraph at line 164
(per Grep) stating that "Thumbnail and screenshot endpoints return `ETag` response headers
based on the cached content digest" and that clients can use `If-None-Match` conditional
requests to avoid downloading unchanged images.

2. Examine the chart thumbnail implementation in
`superset/superset/charts/api.py:729–744,779–43` and the dashboard thumbnail
implementation in `superset/superset/dashboards/api.py:1559–1567,1624–71`: both views
construct a `flask.Response(FileWrapper(image), mimetype="image/png",
direct_passthrough=True)` and do not call `response.add_etag()`, `make_conditional()`, or
use the `etag_cache` decorator from `superset/superset/utils/cache.py:170–272`.

3. Search the backend for conditional request handling and observe that
`superset/superset/utils/cache.py:181–188,245–272` implements ETag and `If-None-Match`
handling via `etag_cache`, and `superset/superset/views/core.py:86,290` applies this
decorator to `explore_json`, but `etag_cache` is never applied to the thumbnail/screenshot
endpoints; additionally, Grep for `"If-None-Match"` under `superset/**/*.py` returns no
matches, confirming the handlers do not inspect that header.

4. Run Superset and request a cached thumbnail URL (e.g., the `thumbnail_url` from
`tests/integration_tests/thumbnails_tests.py:220–223` for dashboards or 237–240 for
charts); inspect the HTTP response and observe that no `ETag` header is present, and that
repeating the request with an `If-None-Match: "abc123..."` header still returns `200 OK`
with the image body instead of `304 Not Modified`, demonstrating that the documented
conditional ETag behavior is not implemented for these endpoints.

Fix in Cursor | Fix in VSCode Claude

(Use Cmd/Ctrl + Click for best experience)

Prompt for AI Agent 🤖 
This is a comment left during a code review.

**Path:** docs/admin_docs/configuration/cache.mdx
**Line:** 164:164
**Comment:**
	*Possible Bug: This statement over-promises behavior that is not implemented in the current thumbnail/screenshot handlers (they don't set `ETag` headers or perform `If-None-Match` conditional handling). Reword to avoid documenting unsupported caching semantics.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
👍 | 👎


```
GET /api/v1/chart/42/thumbnail/
Copy link
Copy Markdown
Contributor

@codeant-ai-for-open-source codeant-ai-for-open-source Bot Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: The example request path is incorrect because the chart thumbnail API requires a digest path segment (/<pk>/thumbnail/<digest>/). Using the documented URL without digest will not hit the intended endpoint, so readers won't be able to reproduce conditional requests correctly. [logic error]

Severity Level: Major ⚠️ 
- ❌ Thumbnail API docs show URL that always 404s.
- ⚠️ Integrators copying example cannot fetch chart thumbnails.
Suggested change
GET /api/v1/chart/42/thumbnail/
GET /api/v1/chart/42/thumbnail/<digest>/
Steps of Reproduction ✅ 
1. Open `docs/admin_docs/configuration/cache.mdx` and locate the thumbnail example at
lines 162–171 (from Grep: lines 162–172), which documents `GET
/api/v1/chart/42/thumbnail/` as the chart thumbnail endpoint used for ETag-based
conditional requests.

2. Inspect the actual chart thumbnail route in `superset/superset/charts/api.py:729–733`,
where the endpoint is defined as `@expose("/<pk>/thumbnail/<digest>/", methods=("GET",))`
and the view `thumbnail(self, pk: int, digest: str, **kwargs)` requires a `digest` path
parameter.

3. Inspect how thumbnail URLs are generated in `superset/superset/models/slice.py:247`,
which returns `f"/api/v1/chart/{self.id}/thumbnail/{digest}/"`, and see this same URL
shape exercised in `tests/integration_tests/thumbnails_tests.py:237–240` where
`thumbnail_url` (including the digest) is fetched and expected to return `200`.

4. Run Superset with thumbnails enabled and issue `GET /api/v1/chart/42/thumbnail/`
(missing digest): because no route is defined for `/api/v1/chart/<pk>/thumbnail/` (only
`/api/v1/chart/<pk>/thumbnail/<digest>/` exists), Flask will return `404 Not Found`, so a
reader following the documented example cannot reproduce the described conditional request
behavior until they add the missing `<digest>` segment.

Fix in Cursor | Fix in VSCode Claude

(Use Cmd/Ctrl + Click for best experience)

Prompt for AI Agent 🤖 
This is a comment left during a code review.

**Path:** docs/admin_docs/configuration/cache.mdx
**Line:** 167:167
**Comment:**
	*Logic Error: The example request path is incorrect because the chart thumbnail API requires a `digest` path segment (`/<pk>/thumbnail/<digest>/`). Using the documented URL without `digest` will not hit the intended endpoint, so readers won't be able to reproduce conditional requests correctly.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
👍 | 👎

If-None-Match: "abc123..."

→ 304 Not Modified (if unchanged)
→ 200 OK (with new image if changed)
```
Comment on lines +183 to +191
Copy link
Copy Markdown
Contributor

@codeant-ai-for-open-source codeant-ai-for-open-source Bot Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 Architect Review — HIGH

The ETag example for thumbnails uses a non-existent endpoint (GET /api/v1/chart/42/thumbnail/), while the actual API requires a digest segment (/api/v1/chart/{id}/thumbnail/{digest}/) and is typically accessed via the image_url returned from the screenshot/thumbnail caching APIs. This incorrect path and implied flow will lead clients following the docs to 404s.

Suggestion: Update the example to use the correct digest-based endpoint shape (e.g. GET /api/v1/chart/42/thumbnail/{digest}/) and clarify that clients should first obtain the image_url (including the digest) from the screenshot/thumbnail caching APIs, then issue conditional GETs with If-None-Match against that URL.

Fix in Cursor | Fix in VSCode Claude

(Use Cmd/Ctrl + Click for best experience)

Prompt for AI Agent 🤖 
This is a comment left during a code review.

**Path:** docs/admin_docs/configuration/cache.mdx
**Line:** 164:172
**Comment:**
	*HIGH: The ETag example for thumbnails uses a non-existent endpoint (`GET /api/v1/chart/42/thumbnail/`), while the actual API requires a digest segment (`/api/v1/chart/{id}/thumbnail/{digest}/`) and is typically accessed via the `image_url` returned from the screenshot/thumbnail caching APIs. This incorrect path and implied flow will lead clients following the docs to 404s.

Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.


This is particularly useful for embedded dashboards and external integrations that periodically poll for updated screenshots — unchanged thumbnails return immediately with no payload.
Comment on lines +181 to +193
Copy link
Copy Markdown
Contributor

@bito-code-review bito-code-review Bot Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Incorrect API documentation

The documentation claims that thumbnail and screenshot endpoints return ETag headers for conditional requests, but the actual endpoints in charts/api.py and dashboards/api.py do not use the etag_cache decorator or add ETag headers. Additionally, the example URL /api/v1/chart/42/thumbnail/ is missing the required parameter; the actual endpoint is /api/v1/chart/42/thumbnail//. This could mislead users expecting ETag functionality that isn't implemented.

Code Review Run #d696cc

Should Bito avoid suggestions like this for future reviews? (Manage Rules)

  • Yes, avoid them


## Distributed Coordination Backend

Superset supports an optional distributed coordination (`DISTRIBUTED_COORDINATION_CONFIG`) for
Expand Down
20 changes: 20 additions & 0 deletions docs/admin_docs/configuration/configuring-superset.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -372,6 +372,26 @@ CUSTOM_SECURITY_MANAGER = CustomSsoSecurityManager
]
```

### PKCE Support

For public OAuth2 clients that cannot securely store a client secret, enable Proof Key for Code Exchange (PKCE) by adding `code_challenge_method` to the `remote_app` configuration:

```python
OAUTH_PROVIDERS = [
{
'name': 'myProvider',
'remote_app': {
'client_id': 'myClientId',
'client_secret': 'mySecret', # may be empty for pure public clients
'code_challenge_method': 'S256', # enables PKCE
'server_metadata_url': 'https://myAuthorizationServer/.well-known/openid-configuration'
}
}
]
```

PKCE (`S256`) is recommended for all OAuth2 flows, even when a client secret is present, as it protects against authorization code interception attacks.

## LDAP Authentication

FAB supports authenticating user credentials against an LDAP server.
Expand Down
16 changes: 15 additions & 1 deletion docs/admin_docs/configuration/theming.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -341,11 +341,25 @@ Available chart types for `echartsOptionsOverridesByChartType`:
- `echarts_heatmap` - Heatmaps
- `echarts_mixed_timeseries` - Mixed time series

### Array Property Overrides

Array properties (such as color palettes) are fully supported in overrides. Arrays are **replaced entirely** rather than merged, so specify the complete array:

```python
THEME_DEFAULT = {
"token": { ... },
"echartsOptionsOverrides": {
# Replace the default color palette for all ECharts visualizations
"color": ["#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd", "#8c564b"]
}
}
```

### Best Practices

1. **Start with global overrides** for consistent styling across all charts
2. **Use chart-specific overrides** for unique requirements per visualization type
3. **Test thoroughly** as overrides use deep merge - nested objects are combined, but arrays are completely replaced
3. **Test thoroughly** as overrides use deep merge for objects, but arrays are completely replaced — always specify the full array value
4. **Document your overrides** to help team members understand custom styling
5. **Consider performance** - complex overrides may impact chart rendering speed

Expand Down
28 changes: 28 additions & 0 deletions docs/docs/using-superset/creating-your-first-dashboard.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,6 +256,34 @@ For example, when running the local development build, the following will disabl
Top Nav and remove the Filter Bar:
`http://localhost:8088/superset/dashboard/my-dashboard/?standalone=1&show_filters=0`

### Table Chart Features

The **Table** chart type has several advanced capabilities worth knowing:

#### Conditional Formatting

Conditional formatting rules highlight cells based on their values. Rules can be applied to:
- **Numeric columns** — color cells above/below a threshold, or use a gradient across a range
- **String columns** — highlight cells matching specific text values or patterns
- **Boolean columns** — color cells that are `true` or `false`, or `null`/`not null`

Each rule has a **"Use gradient"** toggle: enabled applies a varying opacity (lighter = further from threshold), disabled applies a solid fill at full opacity regardless of value.

#### HTML Rendering in Table Cells

Table chart cells can render raw HTML, enabling rich formatting such as hyperlinks, colored badges, and icons directly in the data. Enable this per-column in the chart's **Column Configuration** panel by toggling **Render HTML**.

:::caution
Only enable HTML rendering for columns sourced from data you control. Rendering untrusted HTML can expose users to cross-site scripting (XSS) risks.
:::

#### Column Header Tooltips

Column headers display a tooltip with the column's **Description** from the dataset editor when the user hovers over them. Keep dataset column descriptions up to date to improve chart discoverability.

#### Display Controls

In dashboard view mode (without entering Edit mode), charts with configurable display options expose a **Display Controls** panel accessible from the chart's context menu. This surfaces controls such as Time Grain, Time Column, and layer visibility for applicable chart types — making it easy to adjust a chart's view without going to Explore.
### AG Grid Interactive Table

The **AG Grid Interactive Table** chart type is Superset's fully-featured data grid, suitable for large paginated datasets where the standard Table chart is not enough.
Expand Down
9 changes: 0 additions & 9 deletions docs/docs/using-superset/exploring-data.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -329,15 +329,6 @@ various options in this section, refer to the
Lastly, save your chart as Tutorial Resample and add it to the Tutorial Dashboard. Go to the
tutorial dashboard to see the four charts side by side and compare the different outputs.

### Time Range Natural Language Expressions

The **Custom** time range picker accepts natural language expressions alongside specific dates. Superset supports a range of expressions including:

- Relative: `Last 7 days`, `Last month`, `Last quarter`, `Last year`
- Anchored: `previous calendar week`, `previous calendar month`
- "First of" expressions: `first day of this week`, `first day of this month`, `first day of this quarter`, `first day of this year`, `first week of this year`
- Offsets: `30 days ago`, `1 year ago`, `next week`

### SQL Lab Tips

**Schema and table browser**: The left-side table browser uses a collapsible treeview — click a schema to expand its tables, and click a table to see its columns and sample data inline. This makes navigating large schemas much faster than the previous flat list.
Expand Down
Loading