Metric naming follows the same patterns as naming dbt models, but metrics have their own quirks — particularly the distinction between code names and human labels, and the way different metric types benefit from different naming shapes.
Names vs Labels
The name field is for code. The label field is for humans. Keep them distinct:
name: revenue_growth_momlabel: "Revenue Growth % M/M"Names use snake_case, all lowercase, no special characters. These appear in SQL queries, API calls, and configuration references. They need to be valid identifiers.
Labels use proper capitalization and can include symbols like %, /, and abbreviations that make sense in a dashboard header. Labels are what end users see in BI tools consuming the semantic layer.
A name like rev_grw_pct_mm saves a few characters but becomes unreadable over time. A label like revenue_growth_mom misses the opportunity to present a human-friendly string. Optimize each field independently.
Patterns by Metric Type
Different metric types communicate best with different naming shapes:
| Type | Pattern | Example |
|---|---|---|
| Simple | {noun}_{aggregation} | order_count, revenue_sum |
| Cumulative | {time_period}_{metric} | weekly_active_users, mtd_revenue |
| Derived | {metric}_growth_{period} | revenue_growth_mom, orders_growth_yoy |
| Ratio | {numerator}_per_{denominator} | revenue_per_customer, orders_per_session |
| Conversion | {action}_to_{action}_rate | visit_to_buy_rate, signup_to_activate_rate |
These patterns are not rigid rules. The goal is that someone encountering a metric name for the first time can infer what it measures and how it is calculated. mtd_revenue immediately communicates “month-to-date revenue.” revenue_per_customer is self-evidently a ratio. visit_to_buy_rate describes a funnel step.
The patterns also help when scanning a list of metrics. When all cumulative metrics start with a time period and all ratios use _per_, you can visually group and filter without reading descriptions.
Be Specific
Vague names cause confusion. revenue could mean gross revenue, net revenue, or adjusted revenue. response_time could be milliseconds or seconds. Ambiguity compounds as the metric count grows.
Better:
gross_revenueinstead ofrevenuenet_revenue_after_refundsinstead ofnet_revenueresponse_time_secondsinstead ofresponse_timeresponse_time_p95_msinstead ofp95_response
A metric named revenue requires opening the definition to check which revenue it means. A metric named gross_revenue answers the question in the name.
When AI agents consume metrics-as-code definitions, ambiguous names are especially problematic: a copilot asked about “revenue” will pick the first metric it finds, and if that metric is ambiguous, the answer will be incorrect.
Group Related Metrics with Prefixes
Use consistent prefixes to create metric families:
# Revenue familyrevenue_totalrevenue_per_orderrevenue_growth_momrevenue_mtd
# Customer familycustomer_countcustomer_lifetime_valuecustomer_acquisition_costcustomer_retention_rateWhen someone searches for “revenue,” they find all revenue-related metrics together. This grouping emerges naturally from the prefix convention — no folders, tags, or metadata required.
The prefix should be the business entity, not the technical source. revenue_total rather than orders_revenue_sum. Users think in business terms. They search for “customer” or “revenue,” not “orders semantic model.”
Descriptions Are Not Optional
The description field is the metric’s documentation. It answers the questions that the name cannot:
# What does this measure?- name: arr type: simple type_params: measure: arr_valueCompare with:
- name: arr label: "Annual Recurring Revenue" description: > Sum of annualized contract values for active subscriptions, excluding one-time fees and usage-based charges. Matches the finance team's ARR definition as of Q1 2026. type: simple type_params: measure: arr_valueWhen arr includes one-time fees, the description should say so explicitly — otherwise anyone who needs to know must look elsewhere.
Good descriptions include:
- What the metric measures in plain language
- What is excluded or filtered out
- Which business team’s definition it matches
- Any non-obvious calculation details
Descriptions determine whether a metrics-as-code system is trusted or worked around.
Consistency Over Cleverness
The hardest part of naming is not choosing a good name — it is choosing the same pattern every time. A single metric named monthly_revenue alongside others named revenue_mom and rev_monthly creates navigational chaos.
Pick patterns. Document them. Enforce them in code review. The best naming convention is the one your whole team follows, not the one that is theoretically optimal.