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 |
- 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.
What’s not supported yet
These are skipped with a warning on deploy (details under --verbose):
| MetricFlow feature | Notes |
|---|
ratio metrics | numerator/denominator over other metrics |
derived metrics | expressions over other metrics |
cumulative metrics | require time-spine semantics |
conversion metrics | require entity-journey semantics |
Metric or measure filter: | MetricFlow where-filter templates (e.g. {{ Dimension('order__status') }} = 'completed') don’t map to Lightdash metric filters |
agg: sum_boolean | no Lightdash equivalent |
percentile_type: discrete | Lightdash percentiles always compile to PERCENTILE_CONT |
join_to_timespine, fill_nulls_with, non_additive_dimension | no equivalents |
- 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
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
orders explore two metrics, Total revenue (SUM("orders".amount)) and unique_customers (COUNT(DISTINCT "orders".customer_id)), with no Lightdash-specific YAML. 
