Chart Query Pipeline#

Superset's chart rendering pipeline is a three-phase flow: a frontend query construction phase that converts chart form data into a SQL-agnostic QueryContext, a backend SQL execution phase that returns flat query results, and a frontend transform phase that converts those results into the final visualization.

All chart plugins communicate with the backend exclusively via POST /api/v1/chart/data 1. Each plugin is defined by three coordinated files:

Phase 1: buildQuery → QueryContext#

Each chart's buildQuery.ts calls buildQueryContext(formData, buildQuery?) from @superset-ui/core 2. The helper's two-step logic:

1. buildQueryObject(formData) — Extracts metrics, columns, groupby, time_range, and adhoc_filters into a base QueryObject 3. Filters are split into WHERE/HAVING clauses via processFilters() 4. Time extras (granularity, time grain) are pulled via extractExtras() 5.

2. Chart-specific buildQuery callback — Receives the base QueryObject and returns a modified array. The Timeseries family uses this to inject post_processing operators (pivot, rolling window, time comparison, resample, contribution) and to add an extraMetrics entry for the series-limit sort metric 6.

The returned QueryContext contains the datasource, force flag, result_format, and the final queries array 7. A single chart can issue multiple queries in parallel by returning multiple QueryObject items from its callback 1.

Phase 2: Backend SQL Generation and GROUP BY#

The backend receives the QueryContext and routes each QueryObject through get_sqla_query() in superset/models/helpers.py.

Aggregation is triggered automatically by the presence of any metric 8:

need_groupby = bool(metrics is not None or groupby)

When need_groupby is True, the query builder:

1. Collects groupby columns into groupby_all_columns and adds them to select_exprs 8
2. Builds metric SQL expressions into metrics_exprs — resolving saved metrics via SqlMetric.get_sqla_col() and adhoc metrics via adhoc_metric_to_sqla() 8
3. Merges and deduplicates both lists into the final SELECT 8
4. Applies GROUP BY *groupby_all_columns.values() 8

Adhoc metrics come in two expressionType flavors 8:

• SIMPLE — wraps a column in a named aggregation function (e.g., func.sum(...))
• SQL — passes a raw SQL string through literal_column() after Jinja processing

When no metrics are present, the query falls back to COUNT(*) and omits GROUP BY entirely 8.

Phase 3: transformProps → ECharts Options#

After the backend returns flat row data, the frontend transformProps.ts converts it into chart-ready props. For the Timeseries family (Line, Area, Step, Bar), a single shared Timeseries/transformProps.ts handles all variants 9. The Bar chart simply forces seriesType: 'bar' before delegating to this shared function 9.

The pipeline stages are 9:

1. Data preparation — merges form data defaults, calls rebaseForecastDatum(), runs extractSeries() to produce flat rawSeries
2. Per-series transform — maps each series through transformSeries() in transformers.ts, which converts seriesType → ECharts type and applies color, opacity, stacking, and forecast styling
3. Annotation injection — converts annotation layers into ECharts SeriesOption entries
4. Axis & layout construction — builds x/y axes, swaps if orientation is horizontal, computes padding
5. Option assembly — outputs the final EChartsCoreOption plus cross-filter callbacks (setDataMask), context-menu hooks, and selectedValues

The assembled echartOptions passes to the <Echart> wrapper component, which merges Ant Design theme tokens and calls echartsInstance.setOption() 9.

Known Gotcha: Extra Metrics and Stacked Totals#

The buildQuery for Timeseries charts may inject a timeseries_limit_metric (sort-by metric) into the query via extractExtraMetrics() — a column that appears in the backend result but is not rendered as a visible series. In stacked bar charts with "Only Total" enabled, extractDataTotalValues() in utils/series.ts incorrectly sums this hidden metric into the displayed total, because extraMetricLabels is not passed as an exclusion filter 10. The fix is to compute extraMetricLabels before calling extractDataTotalValues and pass them via an extraMetricLabels opt-out list 10.

Key Source Files#