Skip to main content

Metrics

Synced from semantic-layer

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
  • anchor is the dataset the metric counts rows of. Its time axis is the metric's, unless time_field names another field of the anchor.
  • agg is one of sum, count, count_distinct, avg, min, max, median or percentile (which takes p, between 0 and 100 exclusive).
  • operand is 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 but count needs one. count with no operand counts rows; with one, it counts rows where the operand is not null.
  • filters are part of the metric's meaning, written relative to the anchor (Filters). A query's own WHERE narrows further, but cannot undo them.
  • avg is SQL's AVG: 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.

formatThe value isunit
numbera plain quantity or ratio (0.42, 3.1)optional free label (orders)
currencymoneyits ISO 4217 code (USD) when known
percentpercentage points: 42 means 42%none
fractiona share where 1 is 100%: 0.42 is shown as 42%none
durationa length of timerequired: 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.byMeansTypical metrics
sumadding the groups gives the totalsum and count metrics; a derived metric that only adds and subtracts counts
min, maxcombine with MIN or MAX, never SUMmin, max
componentsre-total each listed component, then apply the exprratios such as revenue / order_count
nonecannot be combined; why says socount_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).