What Is MetricFlow? We Tested Which Metrics Survive OSI

MetricFlow is dbt Labs' open-source engine that turns metric definitions written in YAML into SQL and runs that SQL on your warehouse. A dbt build now also exports those metrics to the Open Semantic Interchange (OSI) format. On October 26, 2026 we exported 16 MetricFlow metrics: 4 came out wrong, 1 was left out, and 2 more keep a filter on a column the file doesn't have, so you'd work out the join by hand.

So here's our take. If you're on dbt, define the metrics that must never drift in MetricFlow and let MetricFlow compute them. Have other tools query it. Don't have them rebuild its metrics from the export, at least not yet.

What is MetricFlow?

dbt's docs call MetricFlow "a SQL query generation tool designed to streamline metric creation across different data dimensions for diverse business needs." You describe your tables once as semantic models: their entities (the keys that join them), dimensions (what you group and filter by) and, in dbt's older YAML format, measures (what you add up). On top of those you define metrics. MetricFlow builds a graph of how the models join, so when someone asks for revenue by customer country, it works out the join and writes the query.

It supports five metric types:

• Simple: one measure, such as total transaction amount.
• Ratio: one metric divided by another, such as cancellations over revenue.
• Cumulative: a running total, a rolling window (last 7 days) or period to date (month to date).
• Derived: an expression over other metrics, including the same metric offset in time, such as this week minus last week.
• Conversion: how many people who did one thing then did another within a window.

MetricFlow started at Transform. dbt Labs bought Transform in 2023 and MetricFlow now powers dbt's semantic layer. The old dbt_metrics package is deprecated and MetricFlow replaced it. If you want the concepts before the tool, start with our semantic layer basics. Coming from ThoughtSpot, a cumulative_sum formula becomes a cumulative metric, and our ThoughtSpot to dbt guide covers the period_agg setting that otherwise gives you wrong monthly totals. Coming from Looker? Here's how LookML maps to MetricFlow. From Metabase? Here's how to move Metabase questions and models into dbt. Leaving Superset? Here's what a Superset export carries into dbt. Moving a Qlik Sense app? Start with its load script. On QuickSight? Here's how its calculated fields move to dbt. On Sigma? Here's how its data models and workbooks move to dbt.

Is MetricFlow free and open source?

Yes. dbt Labs announced on October 14, 2025 that MetricFlow is open source under the Apache 2.0 license. That covers "all of the code required to define metrics and calculate them in multi-dialect SQL."

What's free is the engine. On dbt Core you can define metrics and query them from the command line with mf, but dbt's FAQ says you "won't be able to use the APIs or available integrations to access metrics dynamically." The dbt Semantic Layer, which serves those metrics to BI tools and AI agents, needs a dbt Starter or Enterprise plan. Starter is $100 per user per month with 5,000 queried metrics a month. Our dbt Semantic Layer guide has the full plan comparison and a setup we ran without a dbt account.

Cube Core, Malloy and Lightdash are open source too. Our open-source semantic layer guide compares their licenses and scope with MetricFlow's.

Which MetricFlow metrics survive the OSI export?

OSI is a vendor-neutral format for moving semantic definitions between tools. Snowflake helped found it, and dbt says it's "aligning MetricFlow with the goals of Open Semantic Interchange (OSI)". In July 2026 the project entered the Apache Incubator as Apache Ossie. The pitch is that you define a metric once and any tool can read it.

dbt Core 1.12.6 now writes an OSI file when you run dbt build (target/osi_document.json, format version 0.1.1). To see what's in it, we took MetricFlow's own tutorial project (mf tutorial, metricflow 0.213.0 on DuckDB, written in the YAML format with measures) and added three metrics so all five types were covered. Then we compared each metric's YAML with what landed in the file:

Metric type	Metrics	What the OSI file says	dbt warned?
Simple	7	Same logic as the YAML	No need
Simple with a filter	2	Filter kept, on names like customer__customer_country that no table in the file has	No
Ratio	1	Same logic	No need
Derived	1	Same logic	No need
Derived, offset in time	1	SUM(amount) - SUM(amount), which is always zero	No
Cumulative (all time, 7 days, month to date)	3	SUM(1): the window is gone	Yes
Conversion	1	Left out	Yes

That's 9 of 16 intact. The worst is the week-over-week change, and nothing flags it. In MetricFlow it's this:

- name: transaction_amount_wow_change
  type: derived
  type_params:
    expr: transaction_amount - transaction_amount_prev_week
    metrics:
      - name: transaction_amount
      - name: transaction_amount
        offset_window: 7 days
        alias: transaction_amount_prev_week

In the OSI file it's SUM(transactions.transaction_amount_usd) - SUM(transactions.transaction_amount_usd). The 7-day offset is gone, so any tool that rebuilds the metric from the file reports zero change every week. For the cumulative metrics, dbt printed that the "cumulative window and grain semantics cannot be represented". The conversion metric got its own line: "conversion metrics cannot be represented in the OSI format."

MetricFlow itself handled all 16: it validated every one against the warehouse from the same YAML. The loss is all in the export. The next step, from dbt into Snowflake through Ossie's converters, has gaps of its own, which we hit in our Snowflake semantic layer test.

What to do about it

• Have other tools query MetricFlow, not copy it. BI tools connect through the Semantic Layer APIs, and the dbt MCP server connects "AI tools like Claude and ChatGPT" to them. Its metric tools include list_metrics, query_metrics and get_metrics_compiled_sql. dbt Labs' own dashboard language doesn't query metrics by name yet: in our dbt Charts test, boards kept their numbers after we changed a MetricFlow metric. Some BI tools copy your metrics into their own layer instead; this list of BI tools that read dbt metrics says which.
• If you do export, check the metrics dbt warns about, then the offset ones. The warnings name the cumulative and conversion metrics for you. Derived metrics with an offset_window you have to find yourself.

Our founding engineer Nikolay Alexandrov put it this way: an effective semantic layer "requires owned definitions, baked-in grain and joins, canonical segment filters, a compile-to-SQL step, and tests against the blessed dashboard". MetricFlow is a good compile-to-SQL step. The tests are what catch a week-over-week change stuck at zero.

MetricFlow vs Cube: which should you use?

If your metrics live in dbt, use MetricFlow: the definitions stay in your dbt project, next to the models they're built on. Cube is a different kind of tool, a separate server with its own data model and its own cache.

	MetricFlow	Cube
What it is	An engine inside your dbt project	A server with its own data model
Where queries run	Your warehouse	Its cache when a pre-aggregation fits, else your warehouse
Cache	None of its own (caching is on dbt Enterprise)	Pre-aggregations in Cube Store
How tools connect	mf CLI; Semantic Layer APIs, and MCP through them, on dbt's paid plans	SQL (Postgres-compatible), REST and GraphQL APIs, plus an MCP server
License	Apache 2.0	Apache 2.0 backend, MIT client

MetricFlow adds no server, so its speed is your warehouse's speed. Cube's pre-aggregations are "materialized query results" in Cube Store, and its README says Cube has a built-in relational caching engine "to provide sub-second latency and high concurrency for API requests."

Where Querio fits

Querio reads your dbt project's semantic_manifest.json, so the metrics you keep in MetricFlow stay defined once, in dbt YAML. Querio uses them as written and keeps no second copy. An agent connected through Querio's MCP server can query those metrics by name, as the signed-in user, and the call uses no Querio AI credits. If you're wiring agents to your warehouse, our guide to the BigQuery MCP server shows how to control what an agent's queries can do.

FAQ

Is MetricFlow the same as the dbt Semantic Layer?

No. MetricFlow is the open-source engine that compiles metric definitions into SQL. The dbt Semantic Layer is dbt's hosted service built on it, and dbt calls it "proprietary to dbt, however some components of it are open-source."