Abstract

The dbt Semantic Layer, rebuilt on MetricFlow and generally available since dbt Core 1.6, addresses a structural problem in modern data organizations: the same business metric is computed differently in every BI tool, notebook, and downstream API because the logic lives inside each consumer rather than in a shared, version-controlled definition. By mid-2025, the Semantic Layer has reached production maturity at a number of organizations running Snowflake, BigQuery, and Databricks SQL as their compute backends. This article examines the design philosophy, integration model, and practical constraints teams encounter when centralizing metric definitions through dbt.

The Metric Fragmentation Problem

In a typical data stack without a semantic layer, a revenue metric might be defined differently in a Looker explore, a Tableau calculated field, a Jupyter notebook used by the data science team, and an internal REST API serving the finance dashboard. When the business logic changes - a currency conversion adjustment, a new product line inclusion - each definition must be updated independently. Discrepancies between these definitions produce what practitioners call “metric sprawl,” where leadership sees different revenue numbers depending on which tool they open.

MetricFlow, the open-source engine underlying dbt’s Semantic Layer, introduces a metric definition format in YAML that specifies the measure, the entity (join key), and the dimension set. A revenue metric defined once in the dbt project is queryable through any connected BI tool via the Semantic Layer API, and the SQL is generated by MetricFlow at query time against the configured compute platform.

Integration Architecture

The Semantic Layer exposes a JDBC interface and a GraphQL API. BI tools that have built native integrations - Tableau via the dbt Tableau Connector released in late 2024, Hex, Mode, and the dbt Cloud IDE itself - translate user queries into Semantic Layer requests rather than writing raw SQL against the warehouse. The compute platform executes the generated SQL and returns results; the BI tool never touches the metric logic directly.

For tools without native integrations, dbt Labs ships a Python SDK (dbt-sl-sdk) that allows notebook users and custom applications to query metrics programmatically. This path is widely used by data science teams who want consistent revenue or engagement denominators in model training pipelines without copy-pasting SQL from the analytics engineering team’s Slack messages.

The caching layer is an open architectural gap as of mid-2025. MetricFlow generates and executes SQL on each request; there is no built-in result cache at the Semantic Layer level. Teams on high-concurrency dashboards typically implement caching at the BI tool level or through a query acceleration layer like Materialized Views on their warehouse.

Defining and Versioning Metrics

Metric definitions live as .yml files in the dbt project, versioned in git alongside the models they reference. A metric change goes through the same pull request review process as a model change, giving analytics engineering teams a reviewable audit trail for business logic updates. dbt’s --select syntax can target specific metrics in CI runs, making it practical to test metric SQL generation as part of a pre-merge check.

Dimension inheritance is handled through semantic model references. A user semantic model defines the entity and dimensions once; any metric that joins through user inherits those dimensions automatically. This reduces redundant YAML and ensures that a new dimension added to the user semantic model becomes available across all metrics that reference it without manual updates.

Current Constraints

The Semantic Layer does not yet support arbitrary SQL expressions in metric definitions. Complex metrics requiring window functions across unbounded date ranges, or metrics that require multiple passes over the same table, must be pre-materialized as dbt models and referenced as measures. Teams with very complex KPI trees sometimes find themselves maintaining a hybrid: simple metrics in the Semantic Layer, complex ones as pre-built Mart tables queried directly. The dbt roadmap for late 2025 includes expanded expression support, but teams should audit their metric catalogue before assuming full coverage.