Data governance
7 min

Metrics Layer vs Semantic Layer: The Difference Is a Noun

Key takeaways

  • A metrics layer is a governed record of measures: revenue, churn, and margin, each computed once and the same way in every tool. A semantic layer is a governed record of concepts, with the measures attached to the concept each one is about.
  • The nouns in a metric's formula come from the table. dbt's own documentation says a metric's parameters are name, description, type, label, config, and filter, and that an entity is a concept that serves as a join key.
  • The owner of a definition in a metrics file is a config key. dbt's documentation says changes to meta do not trigger its modified state and are treated as metadata only, so changing the owner is, in the product's own terms, metadata.
  • The competing pages all say a metrics layer is a component of a semantic layer. That is true, and the component they leave out is the concept, which has to be defined before any calculation over it is correct.
  • A metrics layer is enough until an agent is asking, a second domain disagrees, or a regulator asks who decided. At that point the concept needs a definition, a rule, a scope, and a named owner, on the same record as the formula.
In this article
Share

A head of analytics at a retailer ships a metrics layer in a quarter. Churn rate is defined once, every dashboard agrees, and the Monday meeting gets shorter. Then Finance asks why churn excludes trial accounts, and the retention team asks why it includes them. The file has a formula. It has no answer. The metrics layer vs semantic layer question lives in that gap, and the difference between the two is a noun.

A metrics layer is built around a measure: revenue, margin, churn. It says how a number is computed and which fields it can be grouped by. A semantic layer, as it should be, is built around a concept: a customer, an order, a policy. It says what the thing is, who agreed that, and which records qualify, and then it holds the calculation over it. Both are governed records. They are about different nouns.

A metrics layer is organized around a measure and says how to compute it. A semantic layer is organized around a concept and says what it is, with a named owner, before any calculation runs. The first is what the market ships. The second is what an AI agent needs.

What is the difference between a metrics layer and a semantic layer?

In our post What Is a Semantic Layer? we set out the four things a layer holds: concepts, metrics, mappings, and entitlements. Most products hold the second and third. The difference between the two layers is which noun sits at the centre of the record.

The two layers, by the noun each is about

QuestionMetrics layerSemantic layer
The noun at the centreA measure: revenue, churn, marginA concept: customer, order, policy
What it does with that nounComputes it once, the same way everywhereDefines it, names an owner, then attaches the calculations over it
What "customer" is in itA join key with an optional descriptionA class with a definition, a rule, a scope, and a named owner
What a change looks likeA new formula in a file, reviewed in a pull requestA new version of the definition, approved by its owner, the old one still queryable

What does a metrics layer hold about one metric?

Take the file apart. dbt's documentation for metrics (dbt v1.12 and later, read 2026-11-22) lists the parameters of a metric as name, description, type, label, config, and filter. Owner appears in that page's examples as a config key, meta.owner, set to a team handle (dbt documentation). The same vendor's overview of MetricFlow says "Dimensions add context to metrics and without them, a metric is simply a number for all time" (dbt documentation).

One metric, field by field

FieldWhat it holdsWhat kind of word it is
typeSimple, ratio, cumulative, or derived, plus an aggregationThe verb: what is done to the column
expressionThe column, or SQL over itWhat the verb is done to, inherited from the table
dimensionsThe fields it can be grouped byAdjectives: which slice
descriptionFree textA sentence nothing tests
config.meta.ownerA team handleA label on the file

Every row is a verb, an adjective, or a label. The nouns in the formula, the orders summed and the customers counted, arrive with the table name. The product defines the calculation with precision and leaves the noun to whoever built the table.

What would it take for a metrics layer to define a concept?

A metrics layer can define a calculation. It cannot define a concept. It needs defending, because dbt's documentation on entities (last updated 2026-07-20) opens with "Entities are real-world concepts in a business, such as customers, transactions, and ad campaigns". The next sentence says what the product does with them: "In our Semantic Layer models, these entities serve as a join key across semantic models." Name and type are required; the description is optional (dbt documentation). Our post Semantic Layer vs Ontology: Which One Says What a Customer Is shows what the key leaves out.

What a definition needs, and where each layer keeps it

A concept needsIn a metrics fileOn a governed record
A definition in wordsA description string on the entityThe definition, versioned, with the date it took effect
A rule that tests a recordA data test on a column, if someone writes oneA SHACL shape (W3C Shapes Constraint Language), run on every load
A scopeOne definition per projectRetail lines only; the commercial division's customer is a second record
An owner whose approval countsmeta.owner, a key-value pairA named person, an approval date, and a review date

The owner row is where dbt's own documentation makes the point. The meta config "accepts any key-value pairs", and "Changes to meta, including at the column level, don't trigger state:modified. dbt treats meta (and tags) as metadata only" (dbt documentation). So the owner of a definition is a label, and changing it is, in the product's own terms, metadata. A metric definition nobody approved is inferred metadata with a formula attached, and our post Ground Truth: SME-Approved vs Inferred Metadata covers what the approval adds.

Is a metrics layer a component of a semantic layer?

Yes. We read five competing pages on this query, and every one lands there. Kyvos (undated) says "one component of a broader semantic layer"; Querio (2025-12-31) says "a specific part of the larger semantic framework".

Three pages, one answer

PageIts sentence
Cube, updated 2026-08-28"A metrics layer governs measures. A semantic layer governs measures plus entities, dimensions, join paths, and access rules."
A catalog vendor's page on this query, 2026-09-10, updated 2026-09-18"Every metrics layer does semantic-layer work at a smaller scale; not every semantic layer is a metrics layer, since most also model things a KPI formula never touches."
datus, 2026-06-08, updated 2026-06-10"It is the metrics-focused subset of a broader semantic layer."

True, and it leaves out which component comes first. What the pages say the semantic layer adds, entities, dimensions, join paths, and access rules, is the grammar of the warehouse: how tables connect and who may read them. None of it says what a customer is. Cube's page says a metrics layer "gives the agent certified measures; it doesn't necessarily give it the entity graph needed to slice those measures in a way nobody pre-registered". The catalog vendor's page says a metrics layer cannot guarantee that "customer" means the same thing in billing, CRM, and support "because entity resolution sits outside a metrics layer's stated scope". Each then places its own product where the gap is. The missing component is the concept, and it comes first, because every metric is a calculation over concepts someone defined first.

Which comes first, the calculation or the concept?

Here is the retailer's churn rate with its nouns pulled out: customers lost in the period, divided by customers at the start of it. The metrics layer holds the division. Every noun is a decision somebody has to have made.

One formula, three nouns

Noun in the formulaWhat the metrics file holdsWhat has to be decided firstWho decides
CustomerA join key to dim_customerDoes a trial account count? Does a lapsed one?Finance, with a named owner
LostA filter on a status codeCancelled, or ninety days inactive, or both?The retention lead, who disagrees with Finance
The periodA time dimension at month grainCalendar month or billing cycle, and in which time zone?Finance, and it changes at year end

Three nouns, three decisions, two owners who disagree. The metrics layer computes the same disputed number everywhere, which is what the dashboard problem needed. The concept-first order puts each decision on a record with a name on it and attaches the formula to that record. Then the definition and the calculation cannot drift apart. Our post How to Build a Semantic Layer: Platform-Neutral Steps and What Each Native Layer Leaves Out gives that order step by step.

When is a metrics layer enough?

Often. The dashboard problem is real, and a metrics layer is the right tool. Three things change the answer.

Three signals the noun has become the problem

  • An agent is asking. A person carries the concept in their head. An agent composes a query from what was written down, and it finds a key with a description. Our post Semantic Layer vs Text-to-SQL: What a Refusal Is Worth covers why a refusal is only as wide as the nouns someone modelled.
  • A second domain disagrees. The commercial division's customer is an organisation and the retail division's is a person. One formula cannot carry both. A scoped concept can.
  • A regulator asks who decided. "The pull request was approved" names a reviewer. Our post What Is Data Governance for AI? covers who gets to own the definition.

Our post Semantic Layer Tools: Metrics Layers, Native Views and Meaning Layers Compared places each product in its category.

What one test tells you which layer you have?

Change the definition. Decide that trial accounts no longer count, and watch what moves.

The change test

  • In a metrics file. An engineer edits the filter on every metric that counts customers. A reviewer approves the pull request. The previous definition lives in git history.
  • On a governed record. The owner approves one new version of the concept, and every metric over it picks up the change. The previous version stays queryable, with its approver and date.

A layer that passes the second test has the concept as its unit of record. A layer that passes only the first is a metrics layer, whatever the box says.

Where does TopQuadrant fit?

TopQuadrant does not sell the dashboard, the warehouse, or the metrics file. TQ Data Foundation is the governed semantic layer those things read from, and the concept is its unit of record. Every metric carries its business definition, its owner, its calculation, and its mapping to physical columns. The plain-language meaning and the logic live on the same governed asset, so disagreements resolve to a person. Version history shows what the metric meant last quarter and what changed since. When the definition changes, it changes in one place and every consumer picks it up. AI proposes the definitions and the mappings; your experts confirm them. Every definition is validated with SHACL, a standard TopQuadrant helped author, so the record exports whole. We maintain 300 reusable standards-based models, so "customer" starts from governed structure. Your catalog stays, and it syncs. Our semantic layer use case page shows it.

So keep the metrics layer. Give its nouns an owner. A metrics layer says how much. TQ Data Foundation says what, first, with a name on it.

Give your AI the context it's been missing

See how the TQ Data Foundation turns your enterprise knowledge into trusted, Al-ready context.