dbt Semantic Layer: One Metric Definition Across Every BI Tool

Defining a single metric consistently, as covered in Metrics Layer, solves one instance of a recurring problem. The dbt Semantic Layer solves the same problem at architectural scale — a complete semantic model of your business (metrics, dimensions, entities, and how they relate) that any BI tool can query and get identical answers from, without dbt itself becoming a BI tool.

What “Semantic Layer” Actually Means

A semantic layer sits between raw warehouse tables and the tools people use to ask questions of that data. Instead of every BI tool independently translating “show me revenue by region last quarter” into its own SQL, the semantic layer holds the actual business logic — what “revenue” means, what “region” means, how they relate — and every connected tool sends a request through it rather than generating its own SQL from scratch.

                      ┌─────────────┐
Looker  ─────────────▶│             │
Tableau ─────────────▶│  Semantic   │──────▶  Warehouse
Hex     ─────────────▶│   Layer     │
Custom app ──────────▶│ (MetricFlow)│
                      └─────────────┘

Every tool asks the semantic layer the same question the same way; the semantic layer generates correct, consistent SQL underneath, regardless of which tool asked.

Semantic Models: Metrics, Dimensions, and Entities

The Semantic Layer is built on semantic models, which formalize three concepts beyond just metrics:

semantic_models:
  - name: orders
    model: ref('sales_summary')
    entities:
      - name: order
        type: primary
      - name: customer
        type: foreign
    dimensions:
      - name: region
        type: categorical
      - name: order_date
        type: time
        type_params:
          time_granularity: day
    measures:
      - name: revenue
        agg: sum
        expr: total_amount

• Entities are the things being measured or joined on — an order, a customer.
• Dimensions are how you slice a metric — by region, by month, by product category.
• Measures are the raw aggregatable numbers underlying a metric.

Metrics, as covered in Metrics Layer, are then built on top of these semantic models, referencing their measures and dimensions.

Why Entities and Dimensions Matter Beyond Individual Metrics

Declaring region as a dimension once, on the semantic model, means any metric built from orders can be sliced by region automatically — “revenue by region,” “order count by region,” “average order value by region” all reuse the same dimension declaration rather than each metric needing to redefine what “region” means and how to join to it.

This is the core difference from the narrower Metrics Layer: instead of defining calculations one at a time, you’re defining the underlying semantic structure once, and metrics compose from it.

MetricFlow: The Engine Behind the Semantic Layer

MetricFlow is the query-generation engine that translates a semantic request (“monthly revenue, by region, for Q1”) into actual SQL against your warehouse, correctly handling joins between entities and aggregation at the requested dimension grain.

mf query --metrics monthly_revenue --group-by region --start-time 2026-01-01 --end-time 2026-03-31

This is what gets invoked underneath a BI tool’s request when that tool is connected to dbt’s Semantic Layer rather than querying the warehouse directly with its own generated SQL.

Connecting BI Tools to the Semantic Layer

The practical payoff shows up once multiple tools are connected — a Looker dashboard, a Tableau report, and an analyst’s ad hoc query in Hex can all request “monthly_revenue by region” and get byte-for-byte identical numbers, because all three are routed through the same MetricFlow-compiled query logic rather than each tool’s own SQL generation.

This matters most for organizations that have — often unintentionally — accumulated multiple BI tools over time, each with its own history of slightly-drifted metric definitions. The Semantic Layer doesn’t retroactively fix existing dashboards, but it gives new ones, and gradually migrated old ones, a single source of truth to converge toward.

When the Semantic Layer Is Worth Adopting

It’s not a first-day investment for a brand-new dbt project — it earns its value once you have enough models, enough consumers, and enough metric definitions that inconsistency has become an actual recurring problem rather than a theoretical risk.

Common Mistakes

Adopting the Semantic Layer before the underlying models and tests are solid. A consistent, tool-agnostic query layer on top of untested, unreliable models just serves the same wrong number to every tool consistently — consistency isn’t the same as correctness.

Treating dimensions and entities as an afterthought. The real payoff of the Semantic Layer over a narrower Metrics Layer comes from properly declared entities and dimensions enabling metric composition — skipping this and only defining flat metrics gives up most of the benefit.

Expecting existing dashboards to automatically become consistent. The Semantic Layer provides a consistent source going forward; migrating existing, already-built dashboards to actually use it is separate, deliberate work.

Summary

The Semantic Layer is the Metrics Layer’s natural extension — instead of defining individual calculations, you’re defining the underlying business vocabulary once, letting every tool that speaks it get the same answer to the same question.