dbt MetricFlow metrics

If your dbt project defines metrics using MetricFlow (dbt’s semantic layer), the Lightdash CLI can translate them into Lightdash metrics automatically when you deploy. You keep a single source of truth for metric definitions in MetricFlow format, and Lightdash reads them directly from your compiled dbt project. You don’t need a dbt Cloud subscription or the dbt Semantic Layer API, and you don’t need to duplicate the definitions.

How it works

When you run lightdash deploy (or lightdash compile / lightdash preview), the CLI reads your project’s compiled manifest.json, which contains everything MetricFlow knows about your project: the semantic_models (entities, dimensions, measures) and the metrics defined on top of them. These metrics can then be used everywhere Lightdash metrics work (charts, dashboards, the API, AI agents).

dbt parse                # or dbt compile — writes target/manifest.json
lightdash deploy         # translates MetricFlow metrics as part of the deploy

If you define a metric with the same name in both MetricFlow and your model’s meta.metrics, the meta.metrics (Lightdash YAML) definition will take precedence.

Use the latest MetricFlow spec

Lightdash supports the latest and legacy spec, though it’s recommended to use the latest spec.

Legacy spec (dbt Core 1.6+): top-level semantic_models: and metrics: blocks with type_params.
Latest spec (dbt Fusion engine, dbt platform, dbt Core 1.12+): semantic_model: enabled inline on the model, with entities/dimensions on columns and metrics using top-level agg / expr keys.

Supported features

simple metrics, and measures flagged create_metric: true, translate into Lightdash:

MetricFlow	Lightdash metric type
`agg: sum`	`sum`
`agg: count`	`count`
`agg: count_distinct`	`count_distinct`
`agg: average`	`average`
`agg: median`	`median`
`agg: min` / `agg: max`	`min` / `max`
`agg: percentile`	`percentile`
`agg: sum_boolean`	`sum` over `CASE WHEN bool THEN 1 ELSE 0 END`

Also carried over:

Measure expr: bare column references and SQL expressions both become the metric’s SQL.
Labels and descriptions: from the metric, falling back to the measure’s.

Filters

Metric-level and measure-level filter: templates translate when every reference is a {{ Dimension('entity__dimension') }} that resolves on the metric’s own semantic model. The filter is compiled into the metric SQL:

- name: completed_revenue
  type: simple
  type_params:
    measure: total_revenue
  filter: |
    {{ Dimension('order__status') }} = 'completed'

becomes a Lightdash sum metric with SQL CASE WHEN ("orders".status = 'completed') THEN ("orders".amount) END. The dimension’s expr is used when it isn’t a plain column. Filters referencing dimensions on other semantic models, or using other template functions (TimeDimension(), Entity(), Metric()), are skipped with a warning.

Ratio metrics

ratio metrics translate to a non-aggregate Lightdash number metric dividing the two input metrics, when the numerator and denominator both live on the same model:

- name: revenue_per_order
  type: ratio
  type_params:
    numerator: total_revenue
    denominator: order_count

becomes (${total_revenue} * 1.0) / NULLIF(${order_count}, 0) — the * 1.0 avoids integer division on warehouses that truncate, and NULLIF avoids division-by-zero errors. Filtered inputs work too: a numerator with its own filter: (e.g. completion rate = completed orders ÷ all orders) compiles the filter into a hidden helper metric that the visible ratio references. A ratio-level filter: applies to both inputs.

Derived metrics

derived metrics translate to a number metric with the expression rewritten over the input metrics (aliases supported), again when all inputs live on the same model:

- name: revenue_per_customer
  type: derived
  type_params:
    expr: total_revenue / unique_customers
    metrics:
      - name: total_revenue
      - name: unique_customers

becomes ${total_revenue} / ${unique_customers}. Inputs using offset_window or offset_to_grain (time-shifted metrics) are skipped with a warning.

Why same-model only? MetricFlow computes each input metric in its own aggregation subquery — even across unrelated tables — and joins the already-aggregated results. Lightdash compiles one query per explore, so ratio/derived metrics translate faithfully only when all inputs resolve to metrics on the same dbt model. Cross-model inputs are skipped with a warning naming the models involved.

What’s not supported yet

These are skipped with a warning on deploy (details under --verbose):

MetricFlow feature	Notes
`cumulative` metrics	require time-spine semantics
`conversion` metrics	require entity-journey semantics
Cross-model `ratio` / `derived` inputs	inputs must resolve to metrics on the same model (see above)
`offset_window` / `offset_to_grain` inputs	time-shifted inputs have no Lightdash metric equivalent
Cross-model or non-`Dimension()` `filter:` templates	only same-model `{{ Dimension('entity__dim') }}` references translate
`percentile_type: discrete`	Lightdash percentiles always compile to `PERCENTILE_CONT`
`join_to_timespine`, `fill_nulls_with`, `non_additive_dimension`	no equivalents

And these parts of the semantic model are currently skipped:

Entities / joins. MetricFlow joins semantic models implicitly at query time through shared entity keys. Lightdash joins are explicit and authored per-explore (joining tables).
Dimensions and agg_time_dimension. Lightdash generates dimensions from your model’s real columns, so all of your columns are already available as dimensions, and metrics can be grouped by any of them — the MetricFlow dimension definitions aren’t needed. (Dimension expr is honored when resolving filter references.)

Example

A complete working example (both specs, with a reproducible test) lives in the Lightdash repo under examples/metricflow-demo — it exercises every supported shape, including filtered, ratio, derived, and sum_boolean metrics. The short version, in the legacy spec:

semantic_models:
  - name: orders
    model: ref('orders')
    defaults:
      agg_time_dimension: ordered_at
    entities:
      - name: order
        type: primary
        expr: order_id
    dimensions:
      - name: ordered_at
        type: time
        type_params:
          time_granularity: day
    measures:
      - name: total_revenue
        agg: sum
        expr: amount
      # create_metric: true auto-creates a metric — also translated
      - name: unique_customers
        agg: count_distinct
        expr: customer_id
        create_metric: true

metrics:
  - name: total_revenue
    label: Total revenue
    type: simple
    type_params:
      measure: total_revenue

Deploying this project gives the orders explore two metrics, Total revenue (SUM("orders".amount)) and unique_customers (COUNT(DISTINCT "orders".customer_id)), with no Lightdash-specific YAML.

Introduction

Explore and analyze

Build with AI

Build your semantic layer

Workspace and user management

Integrations

Lightdash SDK

Embedding

Self-hosting and deployment

Contact

dbt MetricFlow metrics

How it works

Use the latest MetricFlow spec

Supported features

Filters

Ratio metrics

Derived metrics

What’s not supported yet

Example

​How it works

​Use the latest MetricFlow spec

​Supported features

​Filters

​Ratio metrics

​Derived metrics

​What’s not supported yet

​Example

How it works

Use the latest MetricFlow spec

Supported features

Filters

Ratio metrics

Derived metrics

What’s not supported yet

Example