Why is the `filter:` field on a metric strictly better than a WHERE clause inside a dashboard?

It promotes a constraint to a first-class, reusable, governable metric so every consumer asks for `paying_revenue` and gets the same definition

metrics.yml — The Business Layer

Composing the four metric kinds against semantic models, with constraints and labels.

0/2 done

Overview

Where the business voice lives

Semantic models describe the physical shape (tables, entities, measures). metrics.yml describes the business voice — labels, descriptions, filter constraints — and the composition rules.

The four metric kinds, in YAML

Kind	YAML field	Example
simple	`measure:`	`revenue := SUM(orders.amount_cents)`
ratio	`numerator/denominator:`	`aov := revenue / order_count`
derived	`expr:` + `metrics:`	`gross_margin := (revenue-cogs)/revenue`
cumulative	`measure:` + `cumulative_type_params:`	`revenue_l28d := SUM(amount_cents) over 28d window`

Every metric carries label, description, meta.owner, and optional filter: constraints. The filter: is the feature that makes paying_revenue := revenue WHERE plan != 'free' a first-class metric the LLM and BI can pick like any other — instead of a dangerous one-off WHERE clause baked into a dashboard.

Analogy — the head chef's menu

metrics.yml is a restaurant menu written by the head chef, not the line cooks. The semantic model is the pantry: raw ingredients with their physical properties (tables, columns, measures). The menu is where the chef names dishes a guest can actually order — 'Average Order Value', 'Revenue ($)' — writes a one-line description, and signs each with an owner. The filter: field is the trick that turns a whispered special order ('revenue, but hold the free-tier customers') into a printed, re-orderable dish called paying_revenue that anyone can ask for by name. Once it's on the menu, nobody re-derives it at the table — and nobody forgets the 'hold the free tier' instruction.

Reflect

Pick a high-traffic dashboard. Count how many of its panels secretly carry WHERE plan != 'free', WHERE country != 'US', or similar one-off filters. Each one is a metric the company has not bothered to name. Naming them in metrics.yml is how the semantic layer absorbs tribal knowledge.

›How many implicit metrics live in WHERE clauses across your dashboards today?
›What's the social cost of refusing to name them — who has to be in every meeting because they remember the rule?

Reading in progress · 0 of 2 activities done