Chart Data Table (`chart.data_table`)¶

An optional mini data-grid rendered beneath a chart, with columns pixel-aligned to the chart's x-axis ticks. Direct Excel analogue: "Chart Element → Data Table."

chart:
  type: bar
  x: month
  y: revenue
  data_table:
    - source: sample_size
      format: ",d"
      label: "n"
    - aggregate: sum
      source: revenue
      format: "$.2s"
      label: "Total"

Each list entry is a row. Columns align to the chart's x-axis ticks.

Entry shapes¶

Two shapes, one of each per list entry:

Shape	Keys	When to use
Source row	`source:` (required), `format:`, `label:`	Read a raw per-x value from a query column.
Aggregate row	`aggregate:` + `source:` (both required), `format:`, `label:`	Compute a per-x aggregate across other dimensions (e.g. segment-stacked bars).

Supported aggregate operations¶

sum, avg, min, max, median, count, count_distinct. Exact names — no aliases.

Supported chart types (v1)¶

bar, line, area.

Every other chart type (pie, donut, scatter, kpi, table, arc, waterfall, etc.) rejects the data_table: block with a compile error. Layered charts and charts with a multi-field y: list are also rejected — the attached strip needs a single unambiguous x-encoding.

Rules¶

source: alone is valid only when the query returns at most one row per x-value. On stacked/grouped charts, use aggregate: to resolve — the renderer errors with a pointer at aggregate: if a bare source: is ambiguous.
aggregate: always requires source:.
source: must reference a column present in the chart's query output.
Maximum 40 x-axis ticks (the chart's x-cardinality, not the number of data_table rows). Aggregate or filter in the query before rendering.
Duplicate entries (same source: + aggregate: combination) reject at compile time.
Entries render top-to-bottom in list order.

Styling¶

Themeable at three tiers, each merging into the next:

style.charts.data_table.* — universal defaults.
style.charts.<chart_type>.data_table.* — per-chart-type override.
chart.style.data_table.* — per-chart authored override.

Styleable leaves: font, divider, row, label, number_align, padding_top, padding_bottom.

No column-header row exists on data_table. The divider: block styles a single rule drawn between the plot and the strip top — rule-only, not a header row.

style:
  charts:
    data_table:
      font:
        size: 11
      divider:
        width: 1
      label:
        align: left
      number_align: right
    bar:
      data_table:
        font:
          size: 10     # tighter for dense bar charts

Design references¶

Full specification lives at tasks/workstreams/graph-library/initiatives/chart-attached-data-table/:

spec.md — authoring surface and grammar.
lowering.md — Vega-Lite compilation.
decisions.md — ADR-001..006.

Chart Data Table (chart.data_table)¶