> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# dbt MetricFlow metrics

> Connect Lightdash to your dbt MetricFlow semantic layer metrics

If your dbt project defines metrics using [MetricFlow](https://docs.getdbt.com/docs/build/about-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).

```bash theme={null}
dbt parse                # or dbt compile — writes target/manifest.json
lightdash deploy         # translates MetricFlow metrics as part of the deploy
```

<Info>
  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.
</Info>

### 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**](https://docs.getdbt.com/docs/build/latest-metrics-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`          |

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.

## 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                                                                                                                  |

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](/references/joins)).
* **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`](https://github.com/lightdash/lightdash/tree/main/examples/metricflow-demo). The short version, in the legacy spec:

```yaml theme={null}
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.