# MetricFlow: the metric definitions that compile into SQL instead of into spreadsheets

> MetricFlow is dbt Labs' semantic layer for Python projects: you define metrics, it compiles a request into a dataflow query plan and renders engine specific SQL, so the same metric answers the same way for everyone. The catch is that it needs a dbt project underneath, and its licence has changed twice.

**dbt-labs/metricflow** — MetricFlow allows you to define, build, and maintain metrics in code.

- Repository: https://github.com/dbt-labs/metricflow
- Website: https://docs.getdbt.com/docs/build/about-metricflow
- Stars: 1,866 · Forks: 223
- Language: Python
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/dbt-labs-metricflow

## The metric is the artefact, and it is compiled, not queried

MetricFlow allows you to define, build, and maintain metrics in code. The README describes it as a semantic layer that simplifies defining and managing metrics, and the crucial verb is compiles: it compiles metric definitions into clear, reusable SQL, ensuring consistent and accurate results when analyzing data by relevant attributes, which the project calls dimensions.

That is a small shift in where the work happens. In a typical BI setup, a metric is a formula that lives in a dashboard, a spreadsheet, or someone's head, and it is recalculated by whichever tool asks for it. Here, the metric is a definition in a repository, reviewed like code, and the query that answers it is generated from that definition.

The project explains its own name in a way that describes the architecture rather than the branding. Metric requests are compiled into a dataflow-based query plan, which is then optimized and translated into engine-specific SQL. So a request for revenue by region by month is not a template with holes in it. It becomes a graph of data dependencies, that graph is optimized, and only then is it rendered as SQL for the engine that will run it.

The audience is a data team, and specifically a data team that has outgrown hand-written SQL for shared numbers. The topics on the repository say analytics, business-intelligence, data, data-modeling, metrics and semantic-layer, and the documentation lives in the dbt documentation site rather than in a separate project site.

## Multi-hop joins and ratio metrics are the hard parts it takes on

The abstractions MetricFlow provides are listed in the README, and the list is short enough to be specific.

The first is multi-hop joins between fact and dimension sources. A fact table joined to a dimension, which is joined to another dimension, which is joined to something else, is the kind of join that ends up copied into twelve queries by twelve different people. Handling it in the semantic layer means the join path is declared once.

The second is complex metric types such as ratio, expression and cumulative. A ratio metric is a numerator divided by a denominator, and the difficulty is not the division but making sure both sides are computed over the same population, which is the kind of thing that goes wrong quietly and then gets baked into a board deck.

The third is metric aggregation to different time granularities, meaning the same metric can be rolled up to a day, a week or a quarter without a second definition existing for each level.

The repository structure supports the claim that this is a compiler rather than a query helper. There is a metricflow directory, a metricflow_semantics directory, a metricflow_semantic_interfaces directory, and a dbt-metricflow directory, with three matching test directories, tests_metricflow, tests_metricflow_semantics and tests_metricflow_semantic_interfaces. The separation between semantics, the interfaces to them and the execution layer is what lets the same definitions be consumed by more than one front end. There is also a GLOSSARY.md at the root, which is a reasonable place for the shared vocabulary of an analytics team to live.

## Installing MetricFlow and its dbt prerequisites

The install path is short, and the dependencies around it are not.

The package comes from PyPI, and the README gives the command:

```bash
pip install dbt-metricflow
```

MetricFlow currently serves as a query compilation and SQL rendering library, built to work in conjunction with a dbt project. Using MetricFlow therefore requires a working dbt project and a dbt adapter, and the project provides the dbt-metricflow bundle for that purpose. Other adapters can be installed as optional extras from dbt-metricflow.

Depending on the workflow, you may also need Postgres or Graphviz. The README links their installation instructions and gives Homebrew commands for macOS; it does not say both are required for every installation.

The first real use is the tutorial, and it is a single command:

```bash
mf tutorial
```

One constraint on that command is stated clearly: it must be run from a dbt project root directory. That is not a formality. The tutorial compiles a metric request against your real project, so the output you want to look at is the SQL that your models would have to run, and that is the thing to read before you trust the numbers.

The package metadata gives the runtime envelope: requires-python >=3.10,<3.15, with classifiers for Python 3.10 through 3.14 on both CPython and PyPy, and the development status is listed as 4 - Beta.

## The licence has changed twice, and the current one is Apache 2.0

The licensing story in this project is unusual enough to read carefully, and the README keeps a history of it.

The current state is Apache 2.0. MetricFlow is distributed under the Apache 2.0 license, and the licensing agreement is linked in the repository. The pyproject metadata agrees, with license = Apache-2.0 and the author listed as dbt Labs.

The history is the interesting part. Version 0 to 0.140.0 was covered by the Affero GPL license. Version 0.150.0 to 0.208.2 was covered by the BSL license. Version 0.209.0 and greater is covered by the Apache 2.0 license.

So a company that adopted MetricFlow during the AGPL window, or during the BSL window, is on different terms from one that adopted it recently, and the README states plainly that MetricFlow is source-available software rather than claiming a single uniform licence history. If you are evaluating this for an internal platform, the version you pin decides the obligations, and that is worth checking against your own compliance process rather than assuming the current badge covers the past.

One oddity in the README is the PyPI licence badge, which points at an AGPL-3.0 label, while the licensing section and the package metadata both say Apache 2.0. That looks like a leftover from the earlier licence rather than a change of position, and the LICENSE file in the repository is the place to confirm it.

## The Open Semantic Interchange initiative is the strategic direction

MetricFlow is developed and maintained as part of the Open Semantic Interchange, or OSI, initiative. The README describes that initiative as a collaborative effort among leading technology companies and data practitioners to establish an open standard for defining and exchanging semantic information, enabling AI and BI interoperability across different platforms and tools.

This is worth pausing on, because it changes what the project is. A semantic layer that only compiles to your own warehouse is a productivity tool. A semantic layer whose definitions can be exchanged in a standard format is an attempt to make the metric definitions themselves portable, which is the part that would let two tools agree on what revenue means without a bespoke integration.

The repository layout supports that reading. There is a metricflow_semantic_interfaces package, and it has its own test directory, which suggests the interfaces are treated as a contract with its own tests rather than as an implementation detail of the compiler. There is also a separate sidecar directory and a tagged mf-stdio-sidecar release artifact that shares the version number with the main release, so the project is shipping more than one process shape.

The governance files are a further signal. The root holds GOVERNANCE.md, TENETS.md, ATTRIBUTION.md and GLOSSARY.md, alongside the usual CHANGELOG.md and CONTRIBUTING.md, and the OSI link points at a Snowflake blog post about the initiative, which is a reasonable indication of who else is at the table.

## Version 0.213 with a Beta label, and a repository split into four packages

The release history shows a project shipping often. Version 0.212.0 was published on 2026-08-19 and 0.213.0 on 2026-09-10, and the same 0.213.0 version appears as a separate mf-stdio-sidecar tag published minutes earlier on the same day. The last push to the repository was on 2026-10-13.

Those version numbers are still below 1.0, and the package classifier says Development Status :: 4 - Beta, so the project is telling you it is not finished even while the changelog moves quickly. The README points at the Metricflow Changelog for the latest updates, so the release notes rather than the tags are where the behaviour changes are described.

The build system is Hatch, with the version and the dependency list declared dynamically. The pyproject pulls its requirements through the hatch-requirements-txt plug-in from the requirements-files directory, and the optional extras are named after the environments they set up: dev-env, postgres-env, bigquery-env, databricks-env and redshift-env. That naming is a good sign, because it means the same codebase is expected to run against several warehouses and the differences are handled as environment definitions.

The Makefile shows how the project itself is worked on. Tests run through hatch with pytest, split into the three test directories and run with a parallelism setting that can be overridden, and there is a performance target that writes a performance-report.json and a separate perf-compare target that diffs two of them into a performance-comparison.md. A semantic layer that changes the SQL it emits for every metric in a company needs exactly that kind of regression check, and the presence of one is a better signal than a version number.

## Conclusion

MetricFlow fits a data team that already runs dbt and has the same revenue number defined three different ways in three dashboards, and it fits a team that wants metrics to be reviewable code with a glossary. It does not fit a team without a dbt project, because the README states that using MetricFlow requires a working dbt project and a dbt adapter, and it does not fit a warehouse where the definition of a metric is still a spreadsheet. Before you install, run pip install dbt-metricflow in a dbt project root, follow mf tutorial to see the compiled SQL, and read the licence history in the README, because versions before 0.209.0 were not Apache 2.0.

## FAQ

### What is MetricFlow and what does it do?

MetricFlow is a semantic layer that simplifies defining and managing metrics, compiling metric definitions into clear, reusable SQL so results stay consistent when data is analyzed by dimensions. Metric requests are compiled into a dataflow-based query plan that is then optimized and translated into engine-specific SQL.

### How do I install MetricFlow and run the tutorial?

Install it with pip install dbt-metricflow, which provides the bundle with a dbt adapter, and note that MetricFlow requires a working dbt project and a dbt adapter. You may also need Postgres or Graphviz, then run mf tutorial from a dbt project root directory.

### What licence is MetricFlow released under?

The current versions are covered by the Apache 2.0 license. The README records the history: versions 0 to 0.140.0 were under the Affero GPL, versions 0.150.0 to 0.208.2 under the BSL license, and 0.209.0 and greater under Apache 2.0, and it describes the project as source-available software.

### Does MetricFlow work without dbt?

No. The README states that MetricFlow currently serves as a query compilation and SQL rendering library built to work in conjunction with a dbt project, and that using it requires a working dbt project and a dbt adapter, with the dbt-metricflow bundle provided for that purpose.

### What kinds of metrics does MetricFlow support?

The abstractions cover multi-hop joins between fact and dimension sources, complex metric types such as ratio, expression and cumulative, and metric aggregation to different time granularities.

## Sources

- [dbt-labs/metricflow on GitHub](https://github.com/dbt-labs/metricflow)
- [License: Apache-2.0](https://github.com/dbt-labs/metricflow/blob/main/LICENSE)
- [Project website](https://docs.getdbt.com/docs/build/about-metricflow)
- [README](https://github.com/dbt-labs/metricflow/blob/main/README.md)
- [Releases](https://github.com/dbt-labs/metricflow/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dbt-labs-metricflow