dbt MetricFlow metrics

Connect Lightdash to your dbt MetricFlow semantic layer 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

Requirements

• dbt Core 1.6 or later (manifest schema v10, the first version to include MetricFlow’s semantic layer). The legacy metrics format used by pre-1.6 dbt (calculation_method / expression / time_grains) is no longer read.
• The Lightdash CLI. Translation happens in lightdash compile, lightdash preview, and lightdash deploy. Server-side jobs (scheduled runs from a connected Git repo) don’t currently translate MetricFlow metrics — for now, deploy from the CLI.

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 — so you can always override a translated metric by hand.

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
Metric or measure filter: (same-model Dimension() refs)	filter compiled into the metric SQL as CASE WHEN <condition> THEN <expr> END
ratio metrics (inputs on the same dbt model)	number metric: (${numerator} * 1.0) / NULLIF(${denominator}, 0)
derived metrics (inputs on the same dbt model, no offsets)	number metric with the expr rewritten over ${metric} references

Also carried over:

• Measure expr: bare column references become the metric’s SQL, qualified with ${TABLE} (for example, expr: amount becomes sql: ${TABLE}.amount). Full SQL expressions are used verbatim.
• Labels and descriptions: from the metric, falling back to the measure’s.
• Percentile value: MetricFlow’s legacy spec authors percentile as a 0–1 fraction (percentile: 0.95) and the latest spec authors it as 0–100 (percentile: 95). Both are normalized to Lightdash’s 0–100 scale automatically.
• config.meta.hidden and config.meta.group_label: read from the metric first, falling back to the measure. Use them to hide translated helper metrics from the explore sidebar or group them alongside your other Lightdash metrics. Unknown keys under config.meta are ignored.

Notes on filters, ratio, and derived metrics

• Filters translate when every {{ Dimension('entity__dim') }} reference resolves on the metric’s own semantic model. Cross-model dimension references, and other template functions (TimeDimension(), Entity(), Metric()), skip the metric with a warning.
• Ratio and derived inputs must all resolve to metrics on the same dbt model. In MetricFlow, inputs can come from any semantic model because each input is aggregated in its own subquery; Lightdash compiles a single query per explore, so cross-model inputs are skipped with a warning. Join the relevant models in a Lightdash explore and author a number metric by hand if you need that today.
• Filtered inputs to a ratio or derived metric (for example, a ratio whose numerator has its own filter:) compile the filter into a hidden helper metric that the visible metric references.
• Time-offset inputs to a derived metric (offset_window or offset_to_grain) are skipped with a warning.

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 all resolve on the same dbt model — see the notes above
Derived-metric offset_window / offset_to_grain	time-offset inputs aren’t translated
filter: templates that aren’t same-model Dimension() refs	cross-model dimensions and TimeDimension() / Entity() / Metric() templates don’t map to Lightdash metric filters
agg: percentile without a numeric percentile value	skipped rather than defaulted — set type_params.measure.agg_params.percentile (legacy) or agg_params.percentile (latest)
percentile_type: discrete	Lightdash percentiles always compile to PERCENTILE_CONT
join_to_timespine, fill_nulls_with, non_additive_dimension	no equivalents

Cumulative and conversion metric translation, cross-model ratio/derived inputs, and server-side translation from a connected Git repo are on the roadmap.

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.

Example

A complete working example (both specs, with a reproducible test) lives in the Lightdash repo under examples/metricflow-demo. 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
      - name: status
        type: categorical
    measures:
      - name: total_revenue
        agg: sum
        expr: amount
      - name: order_count
        agg: count
        expr: order_id
      # 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
    # config.meta carries over to the translated Lightdash metric
    config:
      meta:
        group_label: Order metrics
  # Same-model filter → CASE WHEN in the metric SQL
  - name: completed_revenue
    label: Completed revenue
    type: simple
    type_params:
      measure: total_revenue
    filter: |
      {{ Dimension('order__status') }} = 'completed'
  # Same-model ratio → Lightdash `number` metric
  - name: revenue_per_order
    label: Revenue per order
    type: ratio
    type_params:
      numerator: total_revenue
      denominator: order_count

Deploying this project produces four metrics on the orders explore: total_revenue (sum on ${TABLE}.amount, grouped under “Order metrics”), unique_customers (count_distinct on ${TABLE}.customer_id, from the create_metric: true measure), completed_revenue (a sum over CASE WHEN ${TABLE}.status = 'completed' THEN ${TABLE}.amount END), and revenue_per_order (a number metric of (${total_revenue} * 1.0) / NULLIF(${order_count}, 0)) — all with no Lightdash-specific YAML.