Metrics
Source: docs/guide/05-metrics.md at origin/main (3688d236), synced 2026-11-05. Do not edit this page here; change the source and run yarn sync:semantic.
A metric is a governed number. It is either one aggregation over a dataset or arithmetic over other
metrics. It belongs to one domain, and a query asks for it by its bare name: MEASURE(revenue).
An aggregation
name: revenue
display_name: Revenue
anchor: orders
agg: sum
operand: amount
filters:
- {field: is_test, op: equals, value: false}
format: currency
unit: USD
anchoris the dataset the metric counts rows of. Its time axis is the metric's, unlesstime_fieldnames another field of the anchor.aggis one ofsum,count,count_distinct,avg,min,max,medianorpercentile(which takesp, between 0 and 100 exclusive).operandis what is aggregated: a field of the anchor (amount), a field reached over a link (customers.segment, or a path), or a scalar SQL expression. Every aggregation butcountneeds one.countwith no operand counts rows; with one, it counts rows where the operand is not null.filtersare part of the metric's meaning, written relative to the anchor (Filters). A query's ownWHEREnarrows further, but cannot undo them.avgis SQL'sAVG: the sum of the non-null values divided by how many there are.
A derived metric
name: aov
type: derived
expr: revenue / order_count
expr is arithmetic over the bare names of other metrics in the same domain. Each metric it names
must be an aggregation, not another derived metric. Each one computes at its own anchor with its
own time axis, and the results are joined on the query's grouping. That is how conversion_rate: order_count / session_count divides orders by sessions without any link between the two
datasets. Every division reads null when its divisor is zero.
The price is that a derived metric can only be broken down by a field every component's anchor
reaches. conversion_rate by orders.region is refused (FIELD_NOT_REACHABLE), because sessions
cannot reach orders. By time alone it works:
SELECT DATE_TRUNC('week', time) AS week, MEASURE(conversion_rate)
FROM commerce
WHERE time >= :since AND time < :until
GROUP BY ALL
-- refused: FIELD_NOT_REACHABLE
SELECT orders.region, MEASURE(conversion_rate)
FROM commerce
WHERE time >= :since AND time < :until
GROUP BY ALL
exempt_filters lets one component ignore some of the query's filters, so a share can divide a
filtered part by the unfiltered whole:
name: enterprise_revenue_share
type: derived
expr: enterprise_revenue / revenue
exempt_filters:
revenue: [customers.segment] # a query's filter on segment does not narrow the denominator
Format and unit
format says what the number is. unit says how it is measured. Neither ever rescales the
value: a metric serves exactly what its definition computes, and a ratio is a percentage only if
its expr says * 100.
format | The value is | unit |
|---|---|---|
number | a plain quantity or ratio (0.42, 3.1) | optional free label (orders) |
currency | money | its ISO 4217 code (USD) when known |
percent | percentage points: 42 means 42% | none |
fraction | a share where 1 is 100%: 0.42 is shown as 42% | none |
duration | a length of time | required: milliseconds, seconds, minutes, hours or days |
Any other pairing is refused when the metric is written, including unit: %, since a percentage
is a format and not a unit.
default replaces a null result of the requested metric, such as a group with no rows. It is not
applied to a metric used inside another's expr. direction (up_is_good, down_is_good,
neutral), owner, description and ai_context describe the metric and change no number.
Rollup: can rows be added up?
Every metric carries a rollup, worked out from its definition. It tells you whether you may
combine its values from finer groups into a coarser one. It appears in describe output and in
every answer.
rollup.by | Means | Typical metrics |
|---|---|---|
sum | adding the groups gives the total | sum and count metrics; a derived metric that only adds and subtracts counts |
min, max | combine with MIN or MAX, never SUM | min, max |
components | re-total each listed component, then apply the expr | ratios such as revenue / order_count |
none | cannot be combined; why says so | count_distinct, avg, median, percentile |
Studio's describe shows this as the "re-totals by" column: sum, min or max, the component
names (for components), or none.
For components, the coarser value of order_count / session_count * 100 is
SUM(order_count) / SUM(session_count) * 100, not the sum of the ratios. A derived metric that
adds two sums, revenue + fees, is components too, not sum, because a group missing one side
reads null. When by is none, ask
for the metric at the grouping you need instead of adding rows. A query that adds such a column
with SUM is refused (Composing queries).
A metric also carries bounds, the range its value provably cannot leave. A count's is
{"min": 0}, and most metrics have none.
Names and ownership
A metric's name is unique in its domain, so two domains may each own a revenue. An update never
changes the name: renaming is its own action, and the old name keeps working
(Names and changes). A metric cannot move to another domain, and cannot
be deleted while another metric's expr uses it.
You do not have to save a metric to see what it answers. A query can send it as a draft (Answers).