Chart Data Table (`chart.data_table`)¶

An optional mini data-grid attached to a chart, with columns pixel-aligned to the chart's x-axis ticks. The strip position is controlled by style.charts.data_table.position (top or bottom); the default is top (strip above the plot, Excel-style). 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. When label: is omitted on a source or aggregate row, the row stub is derived from source: (successful_launches renders as Successful Launches). Missing, non-finite, or invalid cell values render as a regular dash (-), not as JavaScript sentinel text such as NaN or null. When format: is omitted on a row that reads the chart's primary measure column, the strip inherits chart.format so the chart and strip do not show the same measure with different number formatting.

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. `label:` defaults from `source:` when omitted.
Aggregate row	`aggregate:` + `source:` (both required), `format:`, `label:`	Compute a per-x aggregate across other dimensions (e.g. segment-stacked bars). `label:` defaults from `source:` when omitted.

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.
On dense time-like ordinal axes, strip cells thin to the same visible tick cadence as the axis. This covers both authored coarser label cadences (for example monthly bars with quarterly labels) and runtime labelOverlap: parity culling on narrow bucketed-time bar charts.
Entries render in list order from the row adjacent to the plot outward: top-to-bottom for position: bottom, bottom-to-top for position: top (the default). The row closest to the plot always corresponds to the first entry in the authored list.

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, padding_top, padding_bottom, position.

Value cells align toward their row labels automatically: a left-side y-axis (labels on the left) left-aligns the values, a right-side axis right-aligns them. There is no separate alignment knob.

position accepts "top" (strip above the plot, default) or "bottom" (strip below the plot, legacy layout). Override at any tier to keep below-plot placement:

chart:
  style:
    data_table:
      position: bottom  # legacy below-plot layout for this chart

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

style:
  charts:
    data_table:
      font:
        size: 11
      divider:
        width: 1
      label:
        align: left
      position: top   # default; set bottom for below-plot legacy layout
    bar:
      data_table:
        font:
          size: 10     # tighter for dense bar charts

Chart Data Table (chart.data_table)¶