MetricFlow is production-ready. The dbt Semantic Layer has been generally available for a while now, and most analytics teams have at least one Slack thread about it (yours is probably still unresolved). What's still missing for a lot of teams is a clear mental model for when to migrate and when a good old mart table is still the right call.

This post is that decision framework. Both approaches are valid. Both solve real problems. The question is which one fits your current situation — not which one is theoretically superior.


What metric marts are

A metric mart is a pre-aggregated table: fct_mrr, fct_arr, fct_churn_cohorts. You compute the metric in a dbt model using SQL, materialise it as a table or incremental model, and downstream consumers — BI tools, Python notebooks, Airflow pipelines — query it directly.

The definition of the metric lives in the SQL. The result lives in the warehouse.

-- models/marts/finance/fct_mrr.sql
with subscriptions as (
    select
          subscription_id
        , customer_id
        , plan_id
        , date_trunc('month', started_at)   as cohort_month
        , date_trunc('month', cancelled_at) as churn_month
        , monthly_amount_usd
    from {{ ref('stg_subscriptions') }}
    where status in ('active', 'cancelled')
)

, spine as (
    select
          dateadd('month', seq4(), '2022-01-01'::date) as month_start
    from table(generator(rowcount => 48))
)

select
      s.month_start
    , sub.customer_id
    , sub.plan_id
    , sub.monthly_amount_usd                          as mrr
from spine s
inner join subscriptions sub
    on s.month_start >= sub.cohort_month
    and (sub.churn_month is null or s.month_start < sub.churn_month)

The appeal is real: this is just SQL. Anyone on the team can open it, read it, run it, and debug it. Query time is fast because the aggregation already happened at materialisation. And your BI tool does not need to know anything about MetricFlow or semantic models — it just selects from a table.


What the dbt Semantic Layer is

The dbt Semantic Layer moves the metric definition out of SQL and into YAML. You declare a semantic_model on top of a grain-level model, define measures and dimensions, then define metrics that reference those measures. At query time, MetricFlow translates a metric query into SQL and runs it against the warehouse.

The definition lives in YAML. The result is computed on demand.

version note · 16 Nov 2026

The configuration below uses the earlier semantic_models: and measures: syntax. dbt's v1.12+ documentation describes a newer model- and column-level format. Check the docs for your installed version before copying this example; the mart-versus-semantic-layer trade-offs still apply.

# models/marts/finance/_semantic_models.yml
semantic_models:
  - name: subscriptions
    description: One row per subscription per month
    model: ref('fct_subscriptions_monthly')
    defaults:
      agg_time_dimension: month_start

    dimensions:
      - name: month_start
        type: time
        type_params:
          time_granularity: month
      - name: plan_id
        type: categorical
      - name: customer_segment
        type: categorical

    measures:
      - name: mrr
        description: Monthly recurring revenue in USD
        agg: sum
        expr: monthly_amount_usd

metrics:
  - name: mrr
    description: Total MRR across active subscriptions
    type: simple
    type_params:
      measure: mrr

Once that definition is in place, the same mrr metric is queryable from the dbt Cloud IDE, from Tableau via the semantic layer connector, from a Python script using the MetricFlow SDK, and — and this is the part that matters — from an LLM-backed querying layer like Cortex Analyst.


The key difference

This sounds like a technical implementation detail, but it is actually a fundamental shift in where truth lives. Think of a cinema's lobby showtimes board versus its booking app. The chalkboard is painted once a day — accurate at 9am, wrong the moment a 7pm screening sells out and gets a second showing added. Someone has to notice and repaint it. The booking app has no board at all; it asks the box office system fresh, every single time, so it's never stale but it also never stops asking. A metric mart is the chalkboard. The Semantic Layer is the app that always calls the box office.

With a metric mart, truth is encoded in SQL and manifested as rows in a table. If your definition of MRR changes, you update the SQL, run the model, and the table changes. Every consumer gets the updated number automatically — but they were also all querying a single materialised artifact that you controlled.

With the Semantic Layer, truth is encoded in YAML and executed at query time. If your definition of MRR changes, you update the YAML. Every consumer — regardless of which tool they're using — immediately gets the new definition applied to their next query. No table refresh required. But also no pre-computed result. The warehouse does the work every time someone asks.


When to use metric marts

Metric marts are the right call when your situation looks like this:

Small team, single BI tool, stable definitions. If you have one Tableau server and five dashboards, and MRR has not changed definition in two years, a mart table works perfectly. The complexity of MetricFlow is not justified.

Sub-second query requirements. Metric marts on large datasets with proper clustering will outperform query-time aggregation. If you have a dashboard that loads in 400ms and your stakeholders have noticed, do not swap it for a semantic query.

Downstream consumers that cannot query MetricFlow. Legacy pipelines, external vendors, read replicas with restricted access — if your consumer cannot speak MetricFlow, the Semantic Layer cannot help them.


When to use the Semantic Layer

The Semantic Layer starts to pay off when your situation looks like this:

Multiple consumers using different tools. When Tableau, a Python model-scoring script, and a product analytics notebook all need the same MRR figure, keeping three separate implementations consistent is a maintenance tax. One YAML definition pays that tax once.

Metric definitions change often. If your revenue team redefines "active subscription" twice a quarter, updating three mart tables plus their downstream tests is painful. A single semantic model change propagates everywhere.

You are building an AI querying layer. A semantic layer can provide a useful governed interface to metrics and dimensions, especially when several consumers need the same definitions. It is not the only valid architecture: a curated mart or another constrained query service can also work if it exposes the right definitions, permissions, and validation.


The AI querying angle

An LLM asked to generate SQL against raw mart tables has to infer business meaning and join paths from schema, descriptions, examples, and context. That can produce plausible but wrong queries — especially when grain, time semantics, and business filters are not explicit. A semantic layer or another governed query service narrows the query surface, but it cannot guarantee the agent chose the intended metric or that the underlying data is correct.

A semantic model can be a structured interface. In a setup where the agent queries metrics through MetricFlow, it selects a metric and supported dimensions while MetricFlow constructs the warehouse SQL. The model does not need to generate SQL directly. Other products expose different interfaces, so check the actual tools and enforce their inputs server-side.

# Querying the Semantic Layer via MetricFlow SDK (simplified)
from dbt_metricflow.api import MetricFlowClient

client = MetricFlowClient.from_project("/path/to/dbt/project")

result = client.query(
    metrics=["mrr"],
    group_by=["metric_time__month", "customer_segment"],
    where="metric_time__month >= '2025-01-01'",
)

df = result.result_df

This is one pattern for governed natural-language analytics. A semantic query can ensure that the configured metric definition and joins are used; it cannot by itself ensure that "MRR by segment for Q1" was the user's intended question. Compare the result with trusted examples, test the agent's metric and filter selection, and keep authorization outside the prompt.


Migrating incrementally

You do not need to port your entire mart layer to the Semantic Layer at once. Start with one metric that has multiple consumers or that changes definition frequently. Validate that MetricFlow produces the same results as your mart table. Then expand.

Keep both approaches in production simultaneously during the transition. There is no reason to delete fct_mrr the day you add a semantic model for MRR — sunk cost is a cognitive bias, and a deprecated mart sitting unused for two extra weeks is not the hill to die on. Retire the mart table when you are confident every consumer has migrated.

# dbt_project.yml — run semantic models alongside marts with no conflict
models:
  my_project:
    marts:
      +materialized: table
      +tags: ["mart"]
    semantic:
      +materialized: view   # grain-level source models for semantic_models
      +tags: ["semantic-layer"]

The two approaches are not mutually exclusive during migration. That flexibility is worth using.


Choosing in practice

Mart or Semantic Layer?

One BI tool, stable definitions Stick with metric marts — the Semantic Layer adds overhead you don't need yet.
Three+ tools need the same number Move that metric to the Semantic Layer — one YAML beats three copies of SQL drifting apart.
Sub-second dashboard latency matters Keep it as a mart — query-time computation costs you that latency.
Building an LLM-backed querying layer Prefer a governed metric interface when it fits — a semantic layer is one option; curated marts and constrained query services can also work.
Still unsure Migrate one high-churn metric first, validate parity against the mart, then decide.

Takeaways

  • Metric marts encode truth in SQL; the Semantic Layer encodes it in YAML — this is not a style preference, it determines how and when changes propagate to consumers.
  • Metric marts win on query performance and simplicity — if you have one BI tool, stable definitions, and latency requirements, pre-aggregation is still the right call.
  • The Semantic Layer wins when consumers multiply — three tools querying the same metric definition from one YAML file is strictly better than three copies of the same SQL.
  • For AI querying, use a governed query boundary — a semantic layer is one good option, not a universal requirement. Validate the agent's interpretation and enforce permissions in the application and data platform.
  • Migrate incrementally, starting with one high-churn metric — pick the metric whose definition changes most often, validate parity with your mart, then expand.

Has your team adopted the Semantic Layer? What was the metric that finally made you switch — or what's blocking you from moving?

New blog posts on analytics engineering and practical AI. Subscribe via RSS →