dbt semantic layer and metric trees: how they fit together
dbt defines your metrics in version-controlled YAML and turns them into a single source of truth your whole business can trust. A metric tree does something different. It places your most important metric at the top, decomposes it into the drivers that cause it to move, attaches an owner to each one, and verifies whether the actions taken actually worked. This guide explains how the two layers connect: dbt upstream defining how metrics are calculated, KPI Tree above it defining how they relate, who owns them, and what to do when they move.
11 min read
What the dbt semantic layer is, and where it stops
Definition
The dbt semantic layer is a governed set of metric definitions, written as version-controlled YAML and compiled by MetricFlow, that tells every downstream tool exactly how each metric is calculated: which table it comes from, which column it aggregates, and how. It is the single source of truth for what a metric means. It does not define how one metric drives another, who is accountable when a metric moves, or whether anything was done about it.
Most teams that adopt dbt do so to solve a real and painful problem. Revenue was calculated one way in the finance dashboard, another way in the board deck, and a third way in the spreadsheet someone built last quarter. The number meant something different in every room. The dbt semantic layer fixes this by moving the definition of each metric out of individual reports and into version-controlled YAML. Define Revenue once, and every dashboard, every notebook, and every query that asks for Revenue gets the same answer.
This is genuinely valuable, and it is the right foundation. A metric tree is only as trustworthy as the numbers feeding it, and a governed semantic layer is the cleanest way to guarantee those numbers. dbt does the hard work of making a metric mean one thing.
But notice what the semantic layer is designed to answer. It answers "what is Revenue, and how is it calculated?" It is a precise, governed reference for definitions. It is not designed to answer "why did Revenue fall this month, who owns the input that caused it, and did the fix work?" Those are different questions, and they live in a different layer.
This is not a gap in dbt. It is a boundary. A semantic layer defines how metrics are calculated. It is not the job of a definition to know that Signups drives Revenue, that Sarah is accountable for Signups, or that the campaign relaunch she ran last week actually moved the number. That understanding is about how the business works, not how the data is structured, and it belongs in a layer above the semantic layer.
What a metric tree adds on top
A metric tree takes the metrics your semantic layer already defines and arranges them by cause. The headline metric sits at the top. Beneath it sit the drivers that cause it to move, then the sub-drivers beneath those, down to the inputs your teams actually control. Each edge is a causal link, not just a line on a diagram, so you can trace any change in a top-level outcome back to the specific input that caused it.
The semantic layer gives you a flat, governed list of metrics. The metric tree gives that list a shape. It turns "here are forty metrics, each correctly defined" into "here is how those forty metrics drive each other, and here is the one at the bottom that just moved everything above it."
A causal driver tree
Metrics are connected by edges that are significance-tested and carry a confidence level. The tree is a persistent, governed model of how the business works, not a chart redrawn from scratch every time someone asks a question.
Per-metric RACI ownership
Every metric carries a Responsible, Accountable, Consulted, and Informed assignment. A definition tells you what a metric is. RACI tells you who answers for it when it moves.
Push to the accountable owner
When a metric moves, the accountable owner is told. The signal goes to a person, not to a dashboard that nobody opened. The number stops waiting to be noticed.
A verified-impact loop
When someone takes action on a metric, the loop checks whether the metric actually responded. Effort gets separated from outcome, so you learn which interventions worked rather than just which ones happened.
None of these four are stored in a semantic layer, and none of them should be. Edges, ownership, push, and verification are not properties of how a metric is calculated. They are properties of how a business operates. They are the four shipped primitives that sit above the definition layer and turn a governed catalogue into something you can act on. If you want the longer treatment, see metric decomposition and metric ownership.
How KPI Tree reads your dbt semantic model
KPI Tree does not ask you to redefine your metrics. That would defeat the point of having a semantic layer at all. Instead, it reads the dbt semantic model you have already built and treats it as the source of truth for how each metric is calculated.
The sync works against both dbt Cloud and dbt Core. For dbt Cloud, KPI Tree connects through the dbt Cloud API. For dbt Core, it reads the compiled semantic manifest that MetricFlow produces from your project. Either way, the YAML you have version-controlled stays where it is, owned by your data team, reviewed in pull requests, and unchanged by anything KPI Tree does.
The step that matters most is aggregation detection. When KPI Tree reads a metric from the dbt model, it inspects the underlying measure and detects the aggregation type automatically: a sum, an average, a count, a count of distinct values, and so on. You do not hand-configure how each metric rolls up over time, because the dbt model already encodes it and KPI Tree reads it directly. Get the aggregation wrong and every comparison built on top of the metric is wrong, so reading it from the source rather than guessing is the difference between a tree you can trust and a tree you cannot.
- 1
Connect dbt Cloud or dbt Core
Point KPI Tree at your dbt Cloud account via the API, or at the compiled semantic manifest from your dbt Core project. The connection is read-only against your semantic model.
- 2
Read the semantic model
KPI Tree parses the semantic models, measures, and metrics that MetricFlow exposes. Your YAML definitions remain the single source of truth for how every metric is calculated.
- 3
Detect aggregation automatically
For each metric, KPI Tree inspects the measure and detects whether it sums, averages, counts, or counts distinct values. No manual per-metric aggregation setup, because the dbt model already specifies it.
- 4
Sync the catalogue
The detected metrics land in KPI Tree as a catalogue of governed metrics, each one carrying its dbt definition. When the dbt model changes, a re-sync brings the changes through so the catalogue does not drift.
- 5
Build the tree above the catalogue
With the catalogue in place, you arrange the metrics into a causal tree, assign RACI ownership to each one, and switch on push to the accountable owner. The definitions stay in dbt. The relationships, ownership, and actions live in KPI Tree.
The single source of truth stays in dbt
KPI Tree never rewrites or forks your metric definitions. dbt remains the place where Revenue is defined. KPI Tree reads that definition, detects how it aggregates, and adds the layer above. If a definition changes in dbt, it changes everywhere downstream, including in KPI Tree, because the sync reads the same governed source.
The tree, built from metrics dbt already defines
Once the catalogue is synced, every node in the tree below is a metric your dbt model already defines and calculates. KPI Tree did not invent a single number here. It read each definition from the semantic model, detected how it aggregates, and then arranged the metrics by cause and attached an owner to each.
The values, comparisons, and correlation strengths shown alongside each node are computed by KPI Tree above the catalogue. The definitions underneath them belong to dbt.
Read the tree from the top. Net Revenue fell 9 per cent month on month. The strongest driver of that move is New MRR, and the strongest input beneath New MRR is Signups, down 18 per cent. Sarah is the accountable owner of New MRR, so the push goes to her, not to a dashboard. When she relaunches the acquisition campaign, the verified-impact loop watches Signups and New MRR to confirm whether the action actually moved them.
Every one of those metrics was defined once, in dbt. The tree did not duplicate them. It connected them, owned them, and made them act.
What this means if you own the dbt project
If you are the person who maintains the dbt project, the most important thing to understand is what KPI Tree does not do. It does not ask you to rebuild your metrics, it does not become a second place where definitions live, and it does not quietly drift from your model. The integration is deliberately additive: dbt stays upstream as the plumbing, KPI Tree sits above it as the application layer.
You do not rebuild your metrics
Definitions stay in version-controlled YAML, reviewed in pull requests, owned by your team. KPI Tree reads them. It does not fork them, and it does not ask you to maintain a parallel copy.
Aggregation is detected, not guessed
KPI Tree reads the aggregation type from the dbt measure. There is no per-metric configuration step where someone could pick the wrong roll-up and silently corrupt every comparison built on it.
Any source into one tree
A tree does not have to be all dbt. KPI Tree reads dbt Cloud, dbt Core, and Looker semantic models, and connects to warehouses directly. Metrics from different sources sit in the same tree, decomposed and owned together.
The definitions stay the source of truth
Change a definition in dbt and the change flows downstream on the next sync. There is no second definition in KPI Tree to keep in step, because KPI Tree never held one.
| Layer | dbt semantic layer | KPI Tree above it |
|---|---|---|
| Owns | Metric definitions and calculations | Relationships, ownership, and actions |
| Defines | What a metric is and how it aggregates | How metrics drive each other |
| Lives in | Version-controlled YAML, reviewed in PRs | A persistent causal model above the catalogue |
| Answers | What is Revenue and how is it calculated | Why did Revenue move, who owns it, did the fix work |
| Accountability | No owner attached to a metric | RACI per metric, push to the accountable owner |
| When a metric moves | The number changes in every report | The owner is told and the response is verified |
The honest framing is this. A semantic layer can be made to explain a change, but it does so by transient ad-hoc querying or by an LLM narrating over the numbers, generated fresh each time and gone the moment the conversation ends. A metric tree explains a change by traversing a governed, persistent causal model with a confidence level on every edge and an accountable owner on every node, then verifying that the response worked. One is a query you run again tomorrow. The other is a model your business keeps.
How AI agents use the two layers together
The combination matters most when an AI agent is the one asking the questions. A semantic layer gives an agent governed definitions, so it does not have to guess which table and column to query. That is real and useful. But a definition alone leaves the agent to stitch together comparisons, infer relationships, and invent ownership, none of which the semantic layer holds.
With the metric tree above the dbt catalogue, the agent gets the rest. It reads the causal edges to find the driver that moved, the confidence levels to know which relationship to trust, the RACI assignment to know who to route to, and the verified-impact history to know what has already been tried. The semantic layer tells the agent how Revenue is calculated. The tree tells the agent why it moved and who should act.
This is the difference between an agent that returns a number and an agent that returns an answer. For the full treatment of how an agent consumes this through the protocol, see MCP servers for business performance.
“A semantic layer tells an AI agent what a metric is. The tree above it tells the agent how that metric is driven, who owns it, and whether the last fix worked. One produces a number. The other produces an answer a business leader can act on.”
Where this is heading
The clean separation of layers is what makes the combination durable. dbt keeps getting better at the thing it is built for: governing definitions, version-controlling them, and serving the same number to every tool that asks. As semantic layers mature across the warehouse ecosystem, the definition layer becomes more reliable, more widely adopted, and more standardised. That is good for everything built on top of it.
KPI Tree is built on the assumption that this layer stays where it belongs. The more solid the definitions underneath, the more leverage there is in the layer above. A causal tree is only as trustworthy as the metrics feeding it, so a maturing semantic layer makes the tree more trustworthy, not less.
The direction of travel is toward agents that read both layers at once: the definition from dbt, the causal structure, ownership, and verified impact from KPI Tree. As more questions get asked by software rather than by people clicking through dashboards, the value moves to whichever layer can answer "why, who, and did it work" rather than just "what is the number." Definitions become the floor that everyone stands on. The tree is what you build on that floor.
If you are investing in a dbt semantic layer, you are building the right foundation. The next layer up, the one that turns a governed catalogue into decisions and verified outcomes, is the metric tree.
Continue reading
MCP servers for business performance
From raw data access to actionable understanding
Semantic layer vs business context layer
A semantic layer settles what a metric is. It cannot settle how metrics drive each other, who owns them, or what happens when one moves.
What is a metric tree?
A metric tree maps cause and effect so every team sees what moves the needle
Metric ownership
The most underrated lever in business performance
Keep your dbt definitions, add the layer above
KPI Tree reads your dbt Cloud or dbt Core semantic model, detects aggregation automatically, and syncs the catalogue. Then it adds the causal driver tree, RACI ownership, push to the accountable owner, and verified impact your definitions cannot hold.
