Chart Data API (v1)#

Overview#

The v1 chart data API (/api/v1/chart/data) is Superset's unified query endpoint that replaces the deprecated /superset/explore_json/ endpoint and superset/viz.py pipeline. All chart plugins communicate with the backend exclusively through this endpoint. The migration of all legacy NVD3/legacy charts to v1 was completed as part of a coordinated effort 1, culminating in the removal of the entire legacy pipeline 2.

Architecture#

Request: QueryContext#

The frontend constructs a QueryContext and POSTs it to /api/v1/chart/data. Each chart plugin's buildQuery.ts file is responsible for this construction, using the buildQueryContext helper from @superset-ui/core. A QueryContext contains one or more QueryObject items, allowing a single chart to issue multiple queries in parallel.

Key fields in a QueryObject:

• is_timeseries — enables time-grain bucketing
• metrics — list of metrics to compute
• groupby — dimension columns
• time_range, granularity — extracted via extractExtras() from form data
• post_processing — optional server-side pandas pipeline steps (pivot, resample, rolling, etc.)

Response#

The backend returns an array of query result objects, each containing a data array of flat records (one object per row). This is distinct from the legacy format, which could return pre-shaped nested structures.

Plugin Wiring#

Each chart plugin wires together three pieces 3:

• buildQuery.ts — constructs the QueryContext; absence of this file (and presence of useLegacyApi: true in metadata) was the signal that a plugin used the old path
• transformProps.ts — converts flat query results + form data into renderer-ready props
• controlPanel.tsx — declares chart editor UI controls

Legacy Migration#

Scope#

PR #41714 1 coordinated migration of 15 legacy charts, then removed viz.py (~2,000 lines) and the explore_json endpoints entirely 2. A follow-on PR renamed legacy-plugin-chart-* packages to drop the legacy- prefix 4.

Migration Strategies#

Four approaches were used depending on chart complexity:

1. In-Place Conversion (most charts)#

The most common pattern, used for Parallel Coordinates 5, Country Map 6, Bullet 7, Chord 8, World Map 9, Paired t-test 10, Horizon 11, Time Table 12, Partition 13, and Time-series Period Pivot 14:

• Add buildQuery.ts mirroring the legacy viz.py query_obj() method
• Port get_data() reshape logic to a frontend transformData.ts / transformProps.ts
• Remove useLegacyApi: true from plugin metadata
• Wire loadBuildQuery in index.ts
• No database migration — viz_type keys remain unchanged, so saved charts continue working

2. Server-Side Post-Processing (Rose chart)#

For charts requiring pandas semantics that are hard to replicate in JS, buildQuery.ts attaches a post_processing pipeline to the query object 15. The server executes the pipeline (pivot → resample → rolling → compare → contribution → flatten) and returns shaped data, keeping the frontend transformation simple.

3. Retargeting to ECharts (Bubble)#

Charts with mature ECharts equivalents are redirected via Alembic database migration 16. The saved viz_type is rewritten (e.g., bubble → bubble_v2), and form_data_bak is stored for rollback.

4. Client-Side Resolution (DeckGL Multi-Layer)#

The DeckGL Multiple Layers chart issues an empty queries context from its own buildQuery and lets each layer load independently through its own registered buildQuery/transformProps pair 17.

Case Study: time_pivot Migration#

The Time-series Period Pivot chart (time_pivot, NVD3-based) illustrates the in-place conversion pattern in detail 14:

buildQuery.ts — Issues a single is_timeseries: true query with one metric, mirroring the legacy NVD3TimePivotViz.query_obj().

transformData.ts — Ports the backend reshape logic entirely to the frontend:

1. A rollback() function implements pandas-compatible offset semantics for frequency aliases (AS/A, QS/Q, MS/M, W/W-XXX, D, H, T/MIN) to bucket timestamps into period starts.
2. transformData() filters by DTTM_ALIAS, buckets timestamps, ranks periods most-recent-first (current, -1, -2, …), and shifts older period data onto the latest period's time axis for visual overlap comparison.

transformProps.ts — Detects v1 (flat array) vs. legacy (pre-shaped) payload: flat records go through transformData(), while legacy payloads pass through untouched (backward compatibility).

index.ts changes: removed useLegacyApi: true, added loadBuildQuery, swapped to local transformProps, removed the Legacy metadata tag.

Key Source Files#

References#

• PR #41714 — chore(viz): remove legacy explore_json + viz.py pipeline 1
• PR #41727 — feat(time-pivot): migrate time_pivot chart to v1 chart data API 14
• PR #41750 — chore(viz)!: remove explore_json endpoints, viz.py and the legacy chart data pipeline 2
• PR #41751 — chore(viz): drop the legacy- prefix from migrated chart plugin packages 4