Writing metrics.yml
Translate your paper model into the YAML config that is the single source of truth for the whole layer.
The entire semantic layer is driven by one human-readable file: metrics.yml. It has five top-level keys — database, models (documentation-only notes on each table), join_graph (the join edges the compiler actually reads), dimensions, and metrics. Note the split: models is there for humans; `join_graph` is the operative section the resolver walks to connect tables. Because it's plain YAML, it reviews like a document: a non-engineer can read it and confirm the definitions are right.
The five top-level keys
database: ../data/percolate.db
# 1. models: documentation-only notes on each table (omitted here)
# 2. The join edges the resolver actually walks
join_graph:
- [order_items, orders, "order_items.order_id = orders.order_id"]
- [order_items, products, "order_items.product_id = products.product_id"]
- [orders, customers, "orders.customer_id = customers.customer_id"]
- [subscriptions, customers, "subscriptions.customer_id = customers.customer_id"]
# 3. Dimensions (with per-model overrides where needed)
dimensions:
channel:
sql: customers.channel
per_model:
marketing_spend: marketing_spend.channel
# 4. Metrics
metrics:
revenue:
kind: measure
base: order_items
sql: "SUM(order_items.quantity * order_items.unit_price - order_items.discount)"
filters: ["orders.status = 'completed'"]That's the whole idea. Each metric names its base table and its aggregate SQL. Each dimension names its column. The join graph tells the compiler how to connect them. You edit this file to change what the business can measure — never the query code.
Keeping definitions in YAML rather than Python means a metric change is a config change: reviewable in a pull request, diffable, and safe to hand to an analyst who doesn't write Python. This separation is why semantic layers scale across a company.
The full metrics.yml in the starter kit defines 11 metrics and 9 dimensions. Open it alongside this lesson — everything in it maps directly to the paper model you built in the last lab.