How to build a metric definitions catalogue

What matters here

• A metric catalogue is four parts: one definition per metric, a named owner, versions with effective dates, and links to what uses it.
• Write definitions in business language first, with the query as supporting detail. A definition only an analyst can read does not settle an argument.
• Every metric needs an owner who can change it. A definition owned by the data team is a definition nobody in the business will defend.
• Version definitions rather than editing them, or last year's number silently becomes wrong.
• Record what a metric deliberately excludes. Most disagreements are about the exclusions, not the inclusions.
• Link each metric to the reports using it, so changing a definition shows you what breaks before you change it.

Who this is for

You run data, analytics or the function that keeps being asked why two numbers disagree. What you want is one place that answers what a metric means, who decided that, and what changes if it changes.

How it works in practice

What happens when two dashboards disagree, and how the catalogue makes that a five-minute conversation.

1. 1

   Look the metric up, in business language

   The plain definition first, with the query and source tables as supporting detail underneath.

2. 2

   Read what it deliberately excludes

   Which is where the disagreement almost always is: services, internal accounts, renewals.

3. 3

   See who owns it

   A named person in the business who would defend the number, not the data team who calculated it.

4. 4

   Check which version applied

   Definitions are versioned with effective dates, so a number from March is explained by the definition in force in March.

5. 5

   Propose a change against the metric

   It routes to the owner, and the exchange is kept, because in a year the reasoning is more useful than the definition.

6. 6

   See what a change would break

   Every dashboard, report and model that depends on it, listed before anybody changes anything.

1. 1

   One definition, in language a person can argue with

   Business first, query second, exclusions explicit.

   Copy

   In this Helix project, build me a metric definitions catalogue.
   
   Each metric has a name, a short business definition in plain language, the
   question it answers, its grain (per what, per when), the unit, and a
   worked example with real-ish numbers.
   
   Then, and this is the field most catalogues leave out, an explicit list of
   what the metric deliberately excludes. Most disagreements about a number
   are about the exclusions rather than the inclusions: does revenue include
   services, does an active user include internal accounts, does pipeline
   include renewals. Write those down as their own field and half the
   arguments stop.
   
   Keep the technical detail as supporting information: source tables, the
   query or transformation, the refresh cadence. Useful, but not the
   definition. A definition only an analyst can read cannot settle an
   argument in a leadership meeting.
   
   Let me tag metrics by domain and search across everything, including the
   exclusions.
   
   I sign in through Helix, so do not build a login page. Read the signed-in
   user from the runtime. And do not put any key or connection string in the
   code: if this needs to reach another system, tell me and I will create the
   connection in my workspace.

   Worth knowing. The exclusions field is the cheapest thing here and it resolves most of what these catalogues are built to resolve.

2. 2

   An owner in the business

   Because a definition the data team owns is one nobody will defend.

   Copy

   Give every metric a named owner, and require it. Not the data team: somebody
   in the function that uses the number and would defend it in a meeting.
   
   Add a reviewer too, usually from the data team, who checks that the
   definition and the query actually agree.
   
   Flag any metric with no owner, and any metric whose owner has left, if I
   give you a list of current staff.
   
   Then let anybody raise a question or a proposed change against a metric.
   It routes to the owner, they respond, and the exchange is kept on the
   metric. Six months later the useful artefact is often not the definition
   but the record of why it is that and not the obvious alternative.

3. 3

   Version it, do not edit it

   So last year stays explainable.

   Copy

   Make definitions versioned, with an effective date and a note of what changed
   and why.
   
   Never edit a published version in place. If revenue stops including
   services in April, a number calculated in March was not wrong, and editing
   the definition makes it look as though it was. Anyone reading a historical
   report needs to see which version applied at the time.
   
   Show a diff between versions, and show which version was in force on any
   date I pick.
   
   Add a status: draft, active, deprecated, and replaced by. Deprecated
   metrics stay visible with a pointer to their replacement, because they
   will keep turning up in old decks for years and people need somewhere to
   land.

   Worth knowing. Editing a definition in place is how a company loses the ability to explain its own history. Versions with effective dates cost almost nothing and prevent it.

4. 4

   Show what breaks before it breaks

   Lineage, and the reports that quietly disagree.

   Copy

   Link each metric to what uses it: dashboards, scheduled reports, models,
   and any app that reads it.
   
   Then when somebody proposes a change, show the full list of what depends
   on that definition. Changing a metric is not a data task, it is a
   communications task, and the list of affected reports is the audience.
   
   Add a conflict report: metrics with similar names or similar definitions
   that are not linked. That is where the three-numbers-for-revenue problem
   actually lives, and it is invisible until something goes looking for it.
   
   Report coverage too: how many metrics used in dashboards have no catalogue
   entry at all. That number starts high and it is the honest measure of
   whether the catalogue is finished.

5. 5

   Connect it to real systems

   The step that turns a working prototype into something with your data in it.

   Copy

   Now connect it to the systems we actually run, so it works on real data
   rather than the rows you seeded.
   
   Anything in angle brackets is a placeholder. Swap it for whatever we use
   instead, and have the app name the connection it wants rather than assume
   a vendor, so changing my mind later is a config change and not a rewrite.
   
   <Looker>. Read which dashboards use which metric, so a proposed change
   comes with its blast radius.
   
   <Snowflake>. Read table and column metadata, so a definition can be
   checked against what the query actually does.
   
   <Okta>. Resolve metric owners to real people, and flag any whose owner has
   left.
   
   <Slack>. Route a proposed change to the owner and keep the exchange on the
   metric.
   
   <dbt>. Read the models behind a metric, so the definition can be checked
   against the transformation rather than the dashboard.
   
   <Google Sheets>. Catch the metrics that only exist in a spreadsheet, which
   is where the disputed ones usually live.
   
   <Notion>. Mirror each definition into the docs space, so somebody
   searching a metric name finds the definition and not a dashboard.
   
   Only write where I have said to write. Everything else is read only.
   
   Do not write a key, a token or a connection string anywhere in the code,
   and do not ask me to paste one. Tell me which connections you need and I
   will create each as an authentication in my Helix workspace. Reference
   them by alias.

   Worth knowing. Every name in angle brackets is a placeholder for whatever you run. Helix holds the credential as a workspace authentication, so the app references an alias and never the secret itself.

6. 6

   Ship it

   The last step of every build: a URL, and the right people on it.

   Copy

   Deploy my app.

   Worth knowing. Your assistant runs helix deploy underneath and the app comes back as a URL. Definitions are only authoritative if people can see who owns them, so set Access Control before sharing: everyone reads, owners edit their own metrics.

What it connects to

A catalogue that cannot see what uses a metric cannot tell you what a change would break.

• Looker

  Read which dashboards use which metric, so a proposed change comes with its blast radius.

• Snowflake

  Read table and column metadata, so a definition can be checked against what the query actually does.

• Okta

  Resolve metric owners to real people, and flag any whose owner has left.

• Slack

  Route a proposed change to the owner and keep the exchange on the metric.

• dbt

  Read the models behind a metric, so the definition can be checked against the transformation rather than the dashboard.

• Google Sheets

  Catch the metrics that only exist in a spreadsheet, which is where the disputed ones usually live.

• Notion

  Mirror each definition into the docs space, so somebody searching a metric name finds the definition and not a dashboard.

Each line says whether the app reads, writes or both. Anything not described as writing should be read only.

Named systems are the ones most teams actually run, not a list of the only ones that work. Swap in whatever you use.

Each connection is an authentication in your Helix workspace, referenced by alias. The app names the connection it wants and never holds the credential, so nothing here ends up in your code and any of it can be rotated or revoked without a redeploy.

Related guides