Metric View TOML Reference

Metric-view TOML arranges scalar query results into ordered sections, rows, and columns.

Document#

Complete two-column view

schema_version = 1
name = "My view"

[[sections]]
label = "Movement"
columns = ["Literal", "Saved"]

[[sections.rows]]
label = "Same finger"
indent = 0
cells = [
  { query = "bi.sf.freq * 100", format = "%.2f%%" },
  { metric = "same-finger" },
]

Schema version#

schema_version

Type: integer literal
Required: Required
Default: 1

Identifies the metric-view source format. Use 1 for the current format.

schema_version = 1

View name#

name

Type: nonempty string
Required: Required

The display name shown for the view.

name = "Movement"

Sections#

sections

Type: array of section tables; at least one
Required: Required

Sections are displayed in authored order. Use [[sections]] for each section.

[[sections]]
label = "Movement"
columns = ["Value"]

Section fields#

Section label#

sections.*.label

Type: nonempty string
Required: Required

Heading shown above the section. Labels are presentation text and do not have to be unique.

Columns#

sections.*.columns

Type: array of nonempty strings; at least one
Required: Required

Column headings in display order. Every row in this section must contain exactly the same number of cells as this array.

columns = ["Bigram", "Skipgram"]

Rows#

sections.*.rows

Type: array of row tables; at least one
Required: Required

Rows are displayed in authored order. Use [[sections.rows]] beneath their owning section.

[[sections.rows]]
label = "Same finger"
cells = ["bi.sf.freq * 100"]

Row fields#

Row label#

sections.*.rows.*.label

Type: nonempty string
Required: Required

Heading shown beside the row. Duplicate labels are allowed because rows have positional identity.

Indent#

sections.*.rows.*.indent

Type: integer greater than or equal to 0
Required: Optional
Default: 0

Adds visual indentation to the row label while keeping the same query result.

indent = 1

Cells#

sections.*.rows.*.cells

Type: array of query-string, query-object, or metric-reference cells
Required: Required; at least one

Cells correspond positionally to the section’s columns. Their count must exactly equal the number of column headings.

Write each cell as one nonempty query string, an object containing query and optional format, or an object containing metric and optional format.

cells = [
  "bi.sf.freq * 100",
  { query = "tri.ends.sf.freq * 100", format = "%.2f%%" },
  { metric = "same-finger" },
]

Cell fields#

Every literal or resolved query must be valid and produce one number.

Literal query#

sections.*.rows.*.cells.*.query

Type: nonempty metric query string
Required: Required in a query object; mutually exclusive with metric

Evaluates this exact query independently of saved metrics. The shorthand string cell is equivalent to a query object without format.

The query must produce a scalar number. Reduce collections with .count, .freq, or .map(...).sum. To show percentage points, multiply the frequency in the query, for example bi.sf.freq * 100.

{ query = "bi.sf.freq * 100", format = "%.2f%%" }

Query source

bi.sf.freq * 100

Saved metric reference#

sections.*.rows.*.cells.*.metric

Type: nonempty authored metric Reference ID
Required: Required in a metric-reference object; mutually exclusive with query

Uses the current query of the saved metric whose editable Reference ID exactly matches this string.

Later saved query changes flow into current views. Renaming the metric Reference ID rewrites current references atomically. Historical versions retain their recorded reference identity and query. A missing reference prevents the view from being saved.

{ metric = "same-finger", format = "%.1f%%" }

Number format#

sections.*.rows.*.cells.*.format

Type: string, 1 to 256 characters
Required: Optional; valid only in a query or metric object
Default: %.2f

Contains exactly one fixed-point placeholder: %f or %.<precision>f. Omitting precision uses 6 digits; explicit precision must be an integer from 0 through 100. Write %% for a literal percent sign. Literal prefixes and suffixes are allowed when every other percent sign is escaped.

Formatting changes display only. The format %.2f%% prints two decimals and a percent sign, so the query itself must return percentage points. A successful null result displays as --.

Set a format on each query or metric cell that needs one.

format = "%.2f"

format = "%.1f%%"

format = "Cost: %.0f"