docs: Superset 6.1 documentation catch-up — batch 4#39446
docs: Superset 6.1 documentation catch-up — batch 4#39446michael-s-molina merged 3 commits intomasterfrom
Conversation
- theming.mdx: document ECharts array property overrides (PR #37965) — array values like color palettes are fully supported and replaced entirely (not merged); adds Array Property Overrides section with color palette example - configuring-superset.mdx: document PKCE support for database OAuth2 (PR #37067) — add PKCE section under Custom OAuth2 with code_challenge_method config and when to use it - cache.mdx: document ETag support for thumbnail/screenshot endpoints (PR #37663) — conditional GET with If-None-Match to avoid downloading unchanged images - exploring-data.mdx: document SQL Lab UX improvements (PRs #37298, #37694, #37756) — treeview table browser, Ctrl+F find widget, resizable panels; also adds time range natural language expressions section (PR #37098) - creating-your-first-dashboard.mdx: document Table chart features — boolean and categorical conditional formatting (PRs #36338, #37756), gradient toggle (PR #36280), HTML cell rendering with security note (PR #37685), column header tooltips from dataset descriptions (PR #37179), Display Controls modal in dashboard view (PR #36062) - databases.json: update StarRocks supports_catalog and supports_dynamic_catalog to true — the engine spec (PR #37026) already implemented full catalog support with get_catalog_names(), get_default_catalog(), and SHOW CATALOGS; the committed JSON was stale and did not reflect this Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
✅ Deploy Preview for superset-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
The StarRocks catalog flag fix (supports_catalog, supports_dynamic_catalog) is now handled by the separate generator fix PR (#39449), which regenerates databases.json from Python engine spec class attributes. Removing the manual edit here avoids a merge conflict and keeps the source of truth in the generator. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
![codeant-ai-for-open-source[bot]](https://avatars.githubusercontent.com/u/151810221?s=60&v=4){kind=small}
|
|
||
| ## 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: |
There was a problem hiding this comment.
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.| 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.| Thumbnail and screenshot endpoints return `ETag` response headers based on the cached content digest. Clients can use conditional requests to avoid downloading unchanged images: | ||
|
|
||
| ``` | ||
| GET /api/v1/chart/42/thumbnail/ |
There was a problem hiding this comment.
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.| 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.
| Thumbnail and screenshot endpoints return `ETag` response headers based on the cached content digest. Clients can use conditional requests to avoid downloading unchanged images: | ||
|
|
||
| ``` | ||
| GET /api/v1/chart/42/thumbnail/ | ||
| If-None-Match: "abc123..." | ||
|
|
||
| → 304 Not Modified (if unchanged) | ||
| → 200 OK (with new image if changed) | ||
| ``` |
There was a problem hiding this comment.
🟠 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.![bito-code-review[bot]](https://avatars.githubusercontent.com/in/1061978?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review Agent Run #d696cc
Actionable Suggestions - 1
-
docs/admin_docs/configuration/cache.mdx - 1
- Incorrect API documentation · Line 162-174
Review Details
-
Files reviewed - 5 · Commit Range:
7642d85..9d9f27d- docs/admin_docs/configuration/cache.mdx
- docs/admin_docs/configuration/configuring-superset.mdx
- docs/admin_docs/configuration/theming.mdx
- docs/docs/using-superset/creating-your-first-dashboard.mdx
- docs/docs/using-superset/exploring-data.mdx
-
Files skipped - 0
-
Tools
- Whispers (Secret Scanner) - ✔︎ Successful
- Detect-secrets (Secret Scanner) - ✔︎ Successful
Bito Usage Guide
Commands
Type the following command in the pull request comment and save the comment.
-
/review- Manually triggers a full AI review. -
/pause- Pauses automatic reviews on this pull request. -
/resume- Resumes automatic reviews. -
/resolve- Marks all Bito-posted review comments as resolved. -
/abort- Cancels all in-progress reviews.
Refer to the documentation for additional commands.
Configuration
This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.
Documentation & Help
AI Code Review powered by
| ## 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: | ||
|
|
||
| ``` | ||
| GET /api/v1/chart/42/thumbnail/ | ||
| If-None-Match: "abc123..." | ||
|
|
||
| → 304 Not Modified (if unchanged) | ||
| → 200 OK (with new image if changed) | ||
| ``` | ||
|
|
||
| This is particularly useful for embedded dashboards and external integrations that periodically poll for updated screenshots — unchanged thumbnails return immediately with no payload. |
There was a problem hiding this comment.
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
Co-authored-by: Superset Dev <dev@superset.apache.org> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Michael S. Molina <70410625+michael-s-molina@users.noreply.github.com> (cherry picked from commit 979f60a)
|
Bito Automatic Review Skipped – PR Already Merged |
Co-authored-by: Superset Dev <dev@superset.apache.org> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Michael S. Molina <70410625+michael-s-molina@users.noreply.github.com>
2 participants
SUMMARY
Fourth batch of documentation updates for features merged after 6.0. Continues from #39440, #39441, and #39445.
Documentation updates (5 files):
ECharts array property overrides (
theming.mdx) — documents that array properties (e.g.,colorpalettes) are fully supported inechartsOptionsOverridesand are replaced entirely rather than merged (PR feat(theme): enable generalized ECharts theme overrides for array properties #37965). Adds an "Array Property Overrides" section with a color palette example.OAuth2 PKCE support (
configuring-superset.mdx) — documents thecode_challenge_method: 'S256'option for enabling PKCE on database OAuth2 connections (PR feat(oauth2): add PKCE support for database OAuth2 authentication #37067), with guidance on when to use it.ETag support for thumbnails (
cache.mdx) — documents that thumbnail and screenshot endpoints now returnETagheaders, enabling conditionalIf-None-Matchrequests to avoid downloading unchanged images (PR OSM tiles not available in Superset Mapbox charts #37663).SQL Lab UX improvements (
exploring-data.mdx) — documents three SQL Lab usability improvements: collapsible treeview table browser (PR feat(sqllab): treeview table selection ui #37298), Ctrl+F find widget in editor (PR chore(docker): Bust cache to unblock showtime #37694), and draggable resizable panels (PR feat(table): add conditional formatting support for categorical columns #37756). Also adds the time range natural language expressions section covering "first of" expressions (PR feat(dates): adding handling for first of #37098).Table chart features (
creating-your-first-dashboard.mdx) — documents conditional formatting for boolean and categorical columns (PRs feat(dashboard): implement boolean conditional formatting #36338, feat(table): add conditional formatting support for categorical columns #37756), the gradient/solid toggle on formatting rules (PR feat(table): Gradient Toggle #36280), HTML cell rendering with XSS caution (PR chore(deps): bump aws-actions/configure-aws-credentials from 5 to 6 #37685), column header tooltips from dataset descriptions (PR feat(table): add tooltip to table header #37179), and the Display Controls modal accessible in dashboard view mode (PR feat(dashboard): chart customizations modal and plugins #36062).Database capability fix (1 file):
databases.json) — correctssupports_catalogandsupports_dynamic_catalogtotruefor StarRocks. The engine spec (PR feat(starrocks): add catalog support for StarRocks database connections #37026) already fully implemented catalog support (get_catalog_names(),get_default_catalog(),SHOW CATALOGS) but the committeddatabases.jsonwas not regenerated and still showedfalse. This ensures the generated database documentation page correctly shows catalog support as a StarRocks capability.BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF
N/A — documentation-only changes.
TESTING INSTRUCTIONS
cd docs && npm startto verify MDX renders correctlydatabases.json: confirm that the StarRocks database page now shows the catalog support badgeADDITIONAL INFORMATION
Fifth PR in the 6.1 docs series.