apache / apache/superset

[SIP-225] Proposal for author-configured hierarchical drill-down on dashboard charts

Open
#43,331 10 comments 5 reactions 0 assignees View on GitHub
dashboard:drill-down sip
Dominant language
Python
Stars
74.8k
Forks
18.3k
Avg merge
2d 5h
Merged PRs (30d)
685

Description

### Motivation

Superset today offers two click-driven drill interactions:

- **Drill By** - ad-hoc exploration: on each click the viewer opens a menu and manually picks which column to drill into.
- **Drill to detail**- inspect the raw rows behind a data point.

Both are *exploratory, power-user* tools: they assume the viewer understands the dataset and decides the next dimension on every step. What they don't provide is a **curated, repeatable, single-click drill path for dashboard consumers** — the classic OLAP "click to go one level deeper" interaction (e.g. `country → region → city`) that many BI users expect on executive/consumer dashboards.

The goal of this SIP is to add a **guided, author-configured hierarchical drill-down** that complements Drill By rather than replacing it:

| | Drill By | Hierarchical drill-down |
|---|---|---|
| Who defines the path | Viewer, per click | Chart author, once |
| Interaction | Open menu, choose column | Single click to descend |
| Audience | Analysts who know the schema | Dashboard consumers |
| Navigation back | — | Breadcrumb |
| Consistency | Varies per viewer | Same path for everyone |

**Use cases:** geography (country → region → city), org hierarchy (division → team → person), product taxonomy (category → subcategory → SKU), time granularity (year → quarter → month). In all of these the "story" of the dashboard is a fixed path the author wants every viewer to follow with minimal clicks.

### Proposed Change

Add an opt-in hierarchical drill-down, gated behind a `DRILL_DOWN` feature flag.

**Authoring:** a new **"Drill-down hierarchy"** control-panel section (reusing the existing drag-and-drop dimension selector, so levels can be reordered by dragging). The chart's own primary dimension (x-axis, or first `groupby`) is level 0 automatically; the author only lists the deeper levels.

**Runtime (on a dashboard):**
- Clicking a data point advances the chart to the next level in the hierarchy, scoped to the clicked value, and emits a cross-filter.
- A **breadcrumb** (`country › USA › region › Texas`) appears above the chart; clicking any segment jumps back up.
- Drill state is **browser-only** and **non-destructive**: it never mutates the saved `form_data`, survives incidental chart remounts, and a page refresh returns to the base chart.
- Supported across the ECharts family (Bar/Line/Area/Scatter, Pie/Funnel/Gauge/Radar, BoxPlot, …).

https://github.com/user-attachments/assets/8b33dde5-a827-4a74-8664-b3cbaeb673f7

Reference implementation: PR #41907.

### New or Changed Public Interfaces

- **`form_data`:** a new field `drilldown_hierarchy: string[]` — an ordered list of plain column names (no ad-hoc SQL, so levels match by name). The primary dimension is prepended automatically.
- **Feature flag:** `DRILL_DOWN` (default off).
- **New React components:** `DrillDownHost`, `DrillDownBreadcrumb`, and a `useDrillDownState` hook, plus a shared `drilldownHierarchySection` control.
- **No new or changed REST endpoints or models.** Drill queries reuse the existing chart-data API.

### New dependencies

None. The feature is built entirely on existing Superset/`@superset-ui/core` primitives (the breadcrumb uses the design-system `Breadcrumb` component).

### Migration Plan and Compatibility

- **No database migration.** `drilldown_hierarchy` is additive form-data; charts without it behave exactly as before.
- Fully **backward compatible** and **opt-in** behind the `DRILL_DOWN` flag; the base (undrilled) query is unchanged.
- Forward-looking: the config is intentionally a **thin, column-name-based list** so it can later be *sourced from a dataset/semantic-layer hierarchy* instead of being redefined per chart, aligning with the semantic-layer extensions now landing.

### Rejected Alternatives

- **Extend Drill By instead of a new method.** Drill By is inherently ad-hoc/menu-driven; bolting a fixed guided path onto it would overload a tool with a different mental model. Keeping them separate preserves Drill By's flexibility while adding a distinct guided-consumption interaction.
- **Define the hierarchy only at the dataset/semantic-layer level (not per chart).** Preferable long-term, but the semantic-layer hierarchy primitives are still landing. This SIP keeps the config a thin column-name list so it can migrate to a semantic-layer source without breaking charts. Open question for discussion: should we gate the chart-local config until the semantic-layer source exists, or ship chart-local now and migrate later?
- **Persist drill state in `form_data` / the URL.** Rejected to keep drilling non-destructive and avoid polluting saved charts; state stays client-side only.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing reference implementation PR #41907 and the existing Drill By flow, then trace the chart-data API and control-panel dimension selector. Done means the opt-in DRILL_DOWN path supports configured levels, breadcrumbs, browser-only state, and the listed ECharts chart family without changing saved form_data.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, react
Domain
data-visualization, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.