Metric Definitions: Plain-English Guide

Migration

Metric definitions are one of the quiet foundations of a usable data system. They decide whether two teams are looking at the same business reality or two similar-looking numbers with different rules. This matters during normal dashboard work, and it matters even more during migration, when old reports are rebuilt in a new warehouse, BI tool, semantic layer, or data model.

What a metric definition means

A metric definition is a clear explanation of how a business number is calculated and what it is meant to represent. It is not only a formula. A good definition also explains the source data, the time logic, the filters, the owner, and the situations where the metric should not be used.

For example, monthly recurring revenue might sound simple. But the actual definition may need to answer whether discounts are included, whether paused accounts count, whether taxes are excluded, how currency is handled, and what date decides the month. Without those rules, two dashboards can both say monthly recurring revenue while showing different numbers.

Plain English version: a metric definition is the shared instruction manual for a number.

Why metric definitions break

Metric definitions usually break for ordinary reasons. A team builds a dashboard quickly. Another team copies the logic and changes a filter. A migration rebuilds old reports from screenshots instead of from business rules. A source system changes a status field. A spreadsheet becomes the unofficial truth because it is easier to edit than the warehouse.

The problem is rarely that people do not care about accuracy. The problem is that metric logic often lives in too many places. It may be split across SQL, BI tool calculations, spreadsheet formulas, application code, and tribal memory.

When the same metric is implemented in several places, the definition starts to drift. At first the differences are small. Later, leadership asks why the board deck, sales dashboard, and finance export do not match.

The parts of a good metric definition

A useful metric definition should be specific enough that another analyst can reproduce the number without guessing. It should also be understandable enough that a business stakeholder can tell whether the number matches the business question.

At minimum, define the following pieces:

• Name: The official name of the metric, written consistently.
• Business meaning: What the metric is trying to measure in plain English.
• Formula: The calculation, including numerator and denominator for ratios.
• Grain: The level of detail used before aggregation.
• Source: The trusted tables, models, or systems used to calculate it.
• Filters: Which records are included or excluded.
• Time logic: Which date field is used and how periods are assigned.
• Dimensions: The approved ways to slice the metric, such as region, product, channel, or customer segment.
• Owner: The person or team accountable for the definition.
• Known limitations: Cases where the metric can mislead or does not apply.

This does not require a large governance program. It requires writing down the decisions that already affect the number.

Definition part	Question it answers	Example
Business meaning	What does this number represent?	Customers who completed a first paid order
Formula	How is the number calculated?	Count distinct customer accounts
Grain	What is the base level of detail?	One customer account with its first paid order date
Filters	What is excluded?	Test accounts, internal accounts, cancelled orders
Time logic	Which date assigns the period?	First paid order date
Owner	Who approves changes?	Revenue operations or finance owner

A simple example

Consider a metric called new customers. Many teams assume they know what it means until they try to define it.

One team may count every account created. Another may count only accounts that made a first payment. Another may exclude test accounts, internal accounts, fraud accounts, or imported accounts from an acquisition. None of these choices is automatically wrong. They are different business meanings.

A plain-English definition might say: New customers counts customer accounts that completed their first paid order during the selected period, excluding test accounts, internal accounts, and cancelled orders. The metric is assigned to a period using the first paid order date.

That definition is not perfect for every company. But it is explicit. It gives analysts, engineers, and stakeholders something concrete to review.

Why definitions matter during migration

Migration exposes weak metric definitions. When a team moves from one BI tool to another, rebuilds a warehouse, changes an ERP, or modernizes a data model, old assumptions must be translated into new logic. If the old metric was never clearly defined, the migration team has to reverse engineer meaning from dashboards, SQL, spreadsheets, and stakeholder memory.

This creates risk. The new system may be technically cleaner but still fail trust checks because key metrics do not match the old reports. Sometimes the old reports were wrong. Sometimes the new model is wrong. Often, no one knows because the business definition was never separated from the implementation.

During migration, metric definitions help teams decide what must match exactly, what should be corrected, and what needs a documented break from the old system. That is how migration becomes more than a tool replacement. It becomes a chance to repair the measurement layer.

Common mistakes to avoid

The most common mistake is treating a dashboard number as the definition. A dashboard shows a result. It may not explain all the rules behind the result.

Another mistake is defining metrics only in technical language. SQL is useful, but it is not enough for business alignment. A stakeholder should be able to read the definition and understand what the metric includes, excludes, and means.

A third mistake is allowing multiple official versions of the same metric without naming the difference. If finance revenue and product revenue are intentionally different, name them differently and explain why. Ambiguity is more damaging than honest distinction.

A final mistake is trying to define every possible metric at once. Start with the numbers that drive recurring decisions: revenue, margin, pipeline, active users, retention, churn, conversion, cost, fulfillment, or whatever matters most in the operating rhythm of the company.

Problem	What it looks like	Better approach
Hidden logic	Metric rules exist only inside dashboard calculations	Document the definition and link it to implemented logic
Same name, different rules	Two teams both use revenue but apply different filters	Use distinct names or agree on one official definition
Technical-only definition	Only SQL is documented	Add a plain-English explanation and business owner
No change history	Metric changes without notice	Version the definition and note reporting impact

A practical workflow for defining metrics

A practical workflow does not need to be complex. It should make ownership and review visible.

1. Choose a metric that matters. Start with a metric that appears in executive reporting, financial reporting, operational reviews, or customer-facing analysis.
2. Collect existing versions. Find the dashboard logic, SQL queries, spreadsheet formulas, and stakeholder explanations currently in use.
3. Identify differences. Compare filters, dates, sources, joins, and grouping rules.
4. Write the business definition first. Describe what the number should mean before debating implementation details.
5. Translate the definition into data logic. Map the definition to trusted tables, models, and transformations.
6. Review with owners. Include the business owner and the data owner. The business owner confirms meaning. The data owner confirms implementation.
7. Publish the definition. Put it somewhere people can find it, such as a metrics catalog, documentation site, semantic layer, or governed BI model.
8. Version changes. When the definition changes, record what changed, when it changed, and whether historical reporting was restated.

The goal is not paperwork. The goal is to reduce repeated arguments and prevent silent metric drift.

Where metric definitions should live

Metric definitions can live in several places. The right location depends on the maturity of the data stack and how the company works.

Early teams may keep definitions in a shared document. More mature teams may use a metrics catalog, semantic layer, dbt documentation, BI semantic model, or internal data portal. Some definitions may also be encoded directly in tested transformation models.

The important point is that definitions should not live only in one analyst's memory or only inside one dashboard tile. A definition should be findable, reviewable, and connected to the logic that produces the number.

For durable systems, pair plain-English definitions with implemented logic. The plain-English definition creates alignment. The implemented logic creates repeatability.

How to know your definitions are working

Metric definitions are working when they reduce confusion in normal operating conversations. People may still debate what to do, but they spend less time debating what the number means.

Look for practical signs:

• Analysts reuse existing metrics instead of rebuilding them from scratch.
• Dashboard discrepancies are easier to diagnose because the expected rules are documented.
• Migration testing separates true data defects from intentional definition changes.
• Business owners know who can approve a metric change.
• New team members can understand core metrics without weeks of informal explanation.

This is not about making every number perfect. It is about making important numbers explainable and stable enough to support decisions.

Key takeaways

• A metric definition is the shared rulebook behind a business number.
• Good definitions include meaning, formula, grain, source, filters, time logic, dimensions, owner, and limitations.
• Migration often exposes weak definitions because old dashboard logic must be translated into a new system.
• Do not treat a dashboard tile as the definition. The tile is only one implementation of the rules.
• Start with the metrics that drive recurring decisions instead of trying to define every number at once.

Next step

Pick one high-visibility metric that currently causes disagreement. Write its plain-English meaning, source, filters, time logic, and owner before changing any dashboard logic.