Measures & dimensions

Define certified measures and dimensions: aggregation types, filters, ratios, time intelligence, formatting and the rules that keep numbers consistent.

Updated Sep 26, 20266 min readEdit on GitHub

Measures and dimensions are the words your team uses to talk about data. Define them once, carefully, and every chart, alert and Ask Kimo answer will agree. This page covers the syntax and the patterns we see most often.

Measures

A measure is an aggregation over a column, optionally filtered. Measures can reference other measures to build ratios, and can be marked certified by an editor, which adds a badge everywhere they appear.

Type	SQL equivalent	Example
`sum`	SUM(x)	`revenue`
`count`	COUNT(*)	`orders`
`count_distinct`	COUNT(DISTINCT x)	`active_customers`
`avg` / `median` / `p90`	AVG(x), PERCENTILE_CONT	`avg_order_value`
`ratio`	measure_a / measure_b	`conversion_rate`
`running_total`	SUM() OVER (ORDER BY t)	`cumulative_signups`

models/orders.yml

1measures:2  revenue:3    type: sum4    sql: amount5    filters: [status = 'paid']6    format: currency7    certified: true8  orders:9    type: count10  avg_order_value:11    type: ratio12    numerator: revenue13    denominator: orders14  conversion_rate:15    type: ratio16    numerator: orders17    denominator: web_sessions.sessions18    format: percent

Dimensions

Dimensions are the columns you group and filter by. Besides plain columns, you can define computed dimensions with SQL, bucket numbers into bins, or map raw values to friendly labels.

YAML

1dimensions:2  plan:3    sql: plan_name4  channel:5    sql: coalesce(utm_source, 'direct')6    labels: { google: 'Organic search', meta: 'Paid social' }7  order_size:8    sql: amount9    bins: [0, 50, 200, 1000]10  created:11    sql: created_at12    type: time13    grains: [day, week, month, quarter]

Time intelligence

Any measure on a model with a time dimension gets comparisons for free: revenue.previous_period, revenue.yoy, revenue.delta_pct. Week starts follow the workspace setting (Monday by default) and fiscal years can be offset by month under Settings → Calendar.

Formatting

format: currency uses the source currency, or currency: EUR to force one.
format: percent multiplies by 100 and adds %; set decimals to control precision.
format: duration renders seconds as 2m 14s.
compact: true abbreviates large numbers on KPI tiles (1.2M).

Naming conventions

Use snake_case nouns for measures (active_customers, not count_customers_active) and add a one-line description. Descriptions show up in tooltips and help Ask Kimo choose the right measure, so a good description directly improves answer quality.

Certification and ownership

Anyone with the Editor role can create a measure, but only certified measures carry the blue badge and are preferred by Ask Kimo. Certification is a lightweight review: a second editor checks the definition, the filters and the description, then approves. Certified measures cannot be edited directly; changes go through a draft so that dashboards relying on them do not shift overnight. Kimo keeps a full history of each definition, with who changed what and why.

Use certification for numbers that appear in board decks or are tied to compensation.
Leave exploratory measures uncertified; they are still usable but clearly marked.
Retire a measure with Deprecate: it keeps working for 30 days with a warning, then disappears from pickers.