Metric Definition Worksheet
Define a metric’s business meaning, grain, population, formula, date rules, dimensions, source lineage, tests, owner, and change policy with a blank worksheet.
Use this when
Use this before implementing a shared KPI, reconciling conflicting definitions, or changing a metric that already has downstream consumers.
How to use it
- 01Complete the business meaning and population before writing SQL.
- 02Name the grain and date rule explicitly; both commonly change the answer.
- 03Review one worked example and one exclusion with the metric owner.
Template
Copy it. Replace the brackets. Delete what does not apply.
# Metric definition: [metric name]
## Ownership and status
- **Business owner:** [person or team accountable for meaning]
- **Technical owner:** [person or team accountable for implementation]
- **Status:** [draft / approved / deprecated]
- **Effective date:** [YYYY-MM-DD]
- **Review date:** [YYYY-MM-DD]
- **Version:** [v1.0]
## Decision this metric supports
[What decision, alert, workflow, or comparison uses this metric?]
## Plain-language definition
[Explain what the metric measures without referring to table or column names.]
## Grain and population
- **Entity or event:** [customer, order, subscription, session, invoice, etc.]
- **Output grain:** [one value per…]
- **Included population:** [explicit inclusion rules]
- **Excluded population:** [explicit exclusions and why]
- **Zero-activity entities:** [included / excluded / not applicable]
## Formula
```text
[numerator or aggregation]
--------------------------------
[denominator, if applicable]
```
- **Aggregation:** [sum / count distinct / average / median / ratio / other]
- **Units:** [USD / customers / percentage / days / etc.]
- **Rounding:** [rule and precision]
- **Currency conversion:** [source, rate date, or not applicable]
## Time rules
- **Reporting timestamp:** [event field that assigns the period]
- **Timezone:** [UTC or named business timezone]
- **Period boundary:** [calendar month, fiscal week, rolling 28 days, etc.]
- **Late-arriving records:** [restatement or cutoff rule]
- **Refunds/reversals:** [event date, original event date, or other rule]
## Dimensions allowed
| Dimension | Source | Historical behavior | Notes |
|---|---|---|---|
| [region] | [model.column] | [current / point-in-time] | [unknown handling] |
## Source and lineage
```text
[source systems] → [staging] → [intermediate logic] → [metric model] → [consumers]
```
- **Authoritative source:** [model/table]
- **Primary key or grain check:** [test/query]
- **Refresh expectation:** [schedule and promised availability]
## Null, unknown, and error rules
- **Null numerator:** [rule]
- **Null denominator:** [rule]
- **Division by zero:** [rule]
- **Unknown dimension:** [rule]
- **Deleted or corrected records:** [rule]
## Validation
- [ ] Reconciles to [independent source or prior report] within [tolerance].
- [ ] Key is unique at the declared grain.
- [ ] Required fields are not null.
- [ ] Filters match the written inclusion and exclusion rules.
- [ ] One-to-many joins do not duplicate the numerator or denominator.
- [ ] Boundary dates, zero values, and late records have worked examples.
## Worked examples
### Included
[Small input and expected result.]
### Excluded or handled differently
[Small input, rule applied, and expected result.]
## Consumers and change policy
- **Known consumers:** [dashboards, models, alerts, teams]
- **Breaking changes:** [what counts as breaking]
- **Approval required from:** [owner(s)]
- **Migration window:** [timeline]
- **Deprecation communication:** [channel and notice period]
## Open questions
- [Only genuine unresolved business decisions; remove this section when none remain.]
Learn before you fill it in