One type for one purpose
Each visualization type answers a specific kind of question. Picking the right type is not about aesthetics — it is about making the answer legible at a glance. Every type has its own deep reference page below; each page enumerates exactly which mapping.* and chart.* fields the renderer reads, the cross-filter behavior, worked examples, and common pitfalls.
All visualizations share the same top-level fields (id, title, query, type, filters, format, published). Per-type configuration lives in mapping plus exactly one of: a chart block (for ECharts-based types) or a type-specific block (kpi, grid, matrix) for the DOM-based types.
Supported types
Nine renderers are exposed behind the type: field. Two have aliases (kpi/number → same renderer; grid/table → same renderer).
kpi— single metric with optional delta and comparison. Alias:number.bar— categorical comparison; supports stacking, dual-axis, horizontal orientation.line— time series; supports dual axis and multi-series.pie— part-of-whole composition; supports donut and rose variants.scatter— two-measure correlation; one point per row.heatmap— two-dimensional intensity grid with explicit color scale.funnel— conversion or pipeline stages with drop-off.grid— row-level data table; supports pagination, frozen columns, composite cells. Alias:table.report_matrix— hierarchical report with grouped rows, totals, and PDF export.
Anything else passed as type: is unsupported and rejected at validation time.
The chart block is typed and closed
For ECharts-based types (bar, line, pie, scatter, heatmap, funnel) the chart block is a small, typed surface. Three categories of properties live in it:
- Looky shortcuts — single keys that collapse multiple coordinated decisions into one decision (e.g.
chart.stack: percent,chart.variant: donut,chart.show_value_labels). - Pass-through fields — scalars or arrays mirrored to a specific underlying option (e.g.
chart.center,chart.symbol_size,chart.gap). - Pass-through blocks — nested objects with a curated, snake_case set of properties (e.g.
chart.legend,chart.tooltip,chart.x_axis,chart.y_axis,chart.value_label,chart.label,chart.visual_map).
Any property not listed in the per-type reference page is rejected at validation time. There is no escape hatch for raw chart-library options.
The DOM-based types use their own block
kpi, grid, and report_matrix are not built on a chart library, so they do not have a chart block at all. They use a top-level type-specific block instead — kpi, grid, matrix — plus auxiliary blocks (pagination for grid and report_matrix, comparison for kpi).
Where to look for each topic
- What fields each viz type accepts — the per-type reference page above.
- How filters wire in — Filters.
- Cross-filter behavior — Cross-filtering.
- What Malloy syntax the engine understands — Malloy support.
- How dashboards compose visualizations — Dashboards.
- Adapter divergences — Source adapter differences.
Format string reference (shared by every type)
Number formatting is field-keyed across all viz types. Per-field patterns win over slot patterns; slot patterns win over the root pattern. The pattern grammar:
$#0,0a— abbreviated currency: $1.2M, $340K$#0,00— full currency with two decimals: $1,234.56#0— integer: 1234#.##0,0— number with one decimal: 1,234.5#0,00%— percentage with two decimals: 12.34%#.##0,00%— percentage with more precision: 12.345%EUR#0— currency code prefix: EUR1234#0a— compact: 1.2K, 340K, 1.2M#0b— bytes: 1.2KB, 340MB, 1.2GB
If no format pattern is set for a field, the platform falls back to a default decimal format with two fraction digits.