Semantic layer and MetricFlow

The dbt Semantic Layer is a centralized metric definition framework powered by MetricFlow that allows organizations to define business metrics once in code and serve them consistently across business intelligence tools. Instead of rewriting calculation logic in Tableau, Looker, and hex notebooks, downstream applications query metrics and dimensions by name while MetricFlow generates the appropriate SQL on the fly.

The metric fragmentation problem

Without a semantic layer, metric definitions inevitably diverge across an organization. A finance dashboard might calculate monthly recurring revenue by summing net_amount where status is completed, while marketing defines it by summing gross_amount excluding promotional discounts.

This discrepancy leads to conflicting numbers in executive meetings and forces engineers to spend hours reconciling differences between dashboard queries. The semantic layer eliminates this drift by centralizing the mathematical formula in version-controlled YAML.

Building blocks: models, measures, and dimensions

You configure the semantic layer by defining four core elements in YAML files:

• Semantic models point to existing physical dbt models like fct_orders and define how data should be aggregated and joined.
• Entities represent join keys such as order_id or customer_id that MetricFlow uses to connect different semantic models together.
• Measures are numerical aggregations performed on columns, such as sum of order_amount or count of customer_id.
• Dimensions are categorical or temporal attributes used to slice metrics, such as order_status or ordered_at.

These components give the query engine enough metadata to construct valid SQL.

semantic_models:
  - name: orders_source
    model: ref('fct_orders')
    entities:
      - name: order_id
        type: primary
    measures:
      - name: total_order_amount
        expr: order_amount
        agg: sum
    dimensions:
      - name: order_date
        type: time
        type_params:
          time_granularity: day

Metric definitions can then reference these measures.

How MetricFlow runs queries

When an analyst requests total_order_amount broken down by customer country, MetricFlow inspects the semantic graph:

• It determines which semantic models contain the requested measures and dimensions.
• It calculates the optimal join path between entities without producing accidental cartesian fan-outs.
• It compiles dialect-specific SQL and executes it against the warehouse, returning consistent figures to the requesting client application.

This ensures every consumer views the same business figures regardless of which reporting tool they use.