Tables and metrics

YAML

# table
data:
  inline:
    - month: Jan
      revenue: 100
    - month: Feb
      revenue: 140
columns:
  - key: month
    label: Month
  - key: revenue
    label: Revenue
    format: number
    unit: $
    align: right
sort: {key: revenue, dir: desc}
max_rows: 20
total: true

Use a tagged table YAML fence for structured table authoring. Its fields are generated below. See the readability comparison for the pending series proposal; it is not part of this contract. Tables require data; columns is optional and otherwise derives from the first row. Columns accept string key, label, format and align: left|center|right. Source sorting accepts asc|desc, defaulting to asc. max_rows defaults to 20 and must be a positive integer; total defaults to false. Native details exposes remaining rows; header-click sorting uses the Rust browser runtime and the same core table operation.

Field	Type	Required	Default	Meaning
`title`	text			A caption above the table, also its accessible name.
`data`	data source	yes		The table’s data; exactly one local source is allowed.
`data.inline`	list of mapping			Rows written in the block, each a mapping of column to value.
`data.csv`	report-folder file			A CSV file inside the report folder.
`data.json`	report-folder file			A JSON file of row mappings inside the report folder.
`data.url`	`http` or `https` address			An https data source; current native and browser hosts do not load this field.
`data.sql`	mapping			A SQL query run through a named connector on a host that has a registry.
`data.sql.connector`	text	yes		The name of the connector that runs the query.
`data.sql.query`	report-folder file			A report-relative file holding the SQL; set this or inline, not both.
`data.sql.inline`	text			The SQL text itself; set this or query, not both.
`data.metricflow`	mapping			A MetricFlow query run through a named connector.
`data.metricflow.connector`	text	yes		The name of the connector that runs the query.
`data.metricflow.metrics`	list of text	yes		The metric names to query; at least one.
`data.cache`	mapping			A reference to a cached connector result.
`data.cache.key`	text	yes		The key of the cached result.
`data.sql.params`	mapping			Named values passed to the query.
`data.sql.cache`	mapping			How long the query’s result is reused.
`data.sql.cache.key`	text			The key of the cached result.
`data.sql.cache.ttl`	text			How long the result stays fresh, such as 1h.
`data.sql.cache.freshness`	text			A freshness rule for the result.
`data.sql.cache.refresh`	`true` or `false`			Whether every run refreshes the result.
`data.metricflow.group_by`	list of text			The dimensions to group by.
`data.metricflow.where`	list of text			Filters on the query.
`data.metricflow.order_by`	list of text			The order of the rows.
`data.metricflow.limit`	whole number			The most rows returned.
`data.metricflow.cache`	mapping			How long the query’s result is reused.
`data.metricflow.cache.key`	text			The key of the cached result.
`data.metricflow.cache.ttl`	text			How long the result stays fresh, such as 15m.
`data.metricflow.cache.freshness`	text			A freshness rule for the result.
`data.metricflow.cache.refresh`	`true` or `false`			Whether every run refreshes the result.
`data.cache.ttl`	text			How long the result stays fresh.
`columns`	list of mapping			The columns to show, in order; all columns when omitted.
`columns[n].key`	column name	yes		The data column this table column shows.
`columns[n].label`	text			The column heading.
`columns[n].format`	one of `number`, `number_compact`, `percent` or `year`			The number format of the column’s values.
`columns[n].unit`	text			A unit printed with each value, by the unit rule.
`columns[n].digits`	whole number of significant digits from 2 to 6			Significant digits of the column’s numbers, not decimal places.
`columns[n].align`	one of `left`, `center` or `right`			The alignment of the column’s cells.
`sort`	mapping			The row order.
`sort.key`	column name	yes		The column to sort by.
`sort.dir`	one of `asc` or `desc`		`asc`	The sort direction.
`max_rows`	whole number		`20`	The most rows shown; a positive whole number.
`total`	`true` or `false` or list of column name		`false`	A total row: true sums the numeric columns that are not percentages or years, a list of columns sums those.
`wide`	`true` or `false`		`false`	Whether the table takes the report’s full width instead of the text measure.

Ascending table order is numeric values, then textual values, then missing cells (null and the markers ., NA, N/A, NaN, null, none); descending reverses the values and keeps missing cells last. Within the supported numeric range, precise text retained from CSV sorts by its exact decimal value, including values that share a rounded binary64 representation. A reader who sorts by a column header orders numbers by the value each cell shows: cells that show the same value keep the table’s order, and the page carries no digit a cell does not show. Leading-zero CSV identifiers and authored inline strings remain textual. Numeric totals require numeric cells throughout the column apart from missing cells, which are left out; they include retained CSV numbers, and keep the existing binary64 calculation and selected column format.

YAML

# metric
value: 4234567
label: Q3 revenue
format: number_compact
unit: $
delta: 0.18
delta_label: vs Q2
trend: up

Field	Type	Required	Meaning
`value`	number or text	yes	The headline number or text the block shows.
`label`	text		The caption under the value.
`unit`	text		A unit shown with the value.
`format`	one of `number`, `number_compact`, `percent` or `year`		The number format of the value.
`delta`	number		The change since the last period, shown beside the value.
`delta_label`	text		The caption of the change.
`digits`	whole number of significant digits from 2 to 6		Significant digits of the value and the change.
`trend`	one of `up`, `down` or `flat`		The delta’s colour; it defaults to the sign of the delta.

Metrics require numeric or string value. Table columns, metrics and axes share one format vocabulary, listed in the field tables; another word is block.schema. The retired currency formats become a number format plus unit: $, €, £ or ¥, and authors replace them explicitly in source. Percentages multiply fractional values by 100. Compact values use scale words in tables and metrics (12.5 thousand) and K, M and B on axes. year prints a whole number without grouping (2024, never 2,024), and total: true skips year columns as it skips percent ones. digits (2 to 6) sets the significant digits; only numeric cells of a table are formatted (identifiers such as 001 stay text). A unit ending in a currency symbol ($, US$, €, £, ¥) leads the value; any other unit follows it with the chart axis rule (68.2%, 12 users). Formatting can round displayed values without changing source data.

A metric renders as a stat line, never a filled panel: the value with its unit in the display face at size-h1 with lining tabular figures, then the label and the signed delta at the small size. The delta carries the trend colour (trend: up and down use the up and down tokens). The style’s components.metric.style chooses the rules around the stat; knockout also sets the value in the accent.