metricflow

MetricFlow 0.212.0 - August 11, 2026

Features

• Add Athena adapter and SQL rendering support (#979)

Fixes

• Use TIMESTAMP_TRUNC instead of DATETIME_TRUNC for BigQuery (#2078)
• Add parentheses around user-supplied filter strings (#2066)
• Name auto-generated OSI ratio sub-metrics without dunders so they pass semantic manifest name validation (#2091)

Under the Hood

• Restore dbt-metricflow dependency changes in release flow (#2055)
• Remove old release helpers (#2056)
• Simplify output column orderers (#2064)
• Add option to use legacy column order (#2065)
• Limit result cache in group-by item resolver (#2075)
• Update error handling for invalid percentile configuration (#2076)
• Update emitted messages in ExecutionTimer (#2084)
• Clean up method duration logging (#2085)
• Improve invalid state file handling in the release tool (#2088)
• Update release tool to use ort instead of fossa (#2102)
• Add CI pipeline to compile MetricFlow into standalone Nuitka binaries for macOS, Linux, and Windows, and publish them as versioned GitHub Release artifacts for embedding in dbt-core v2 (Fusion) (#2106)

Dependencies

• Update DuckDB dev dependency to >= 1.5 (#2051)
• Update dbt-core to >=1.11, <1.13 (#2105)
• Support Python 3.14 in dbt-metricflow (#2108)

Contributors

• @QMalcolm (#2106)
• @courtneyholcomb (#2078)
• @faaabi963 (#979)
• @ota2000 (#2091)
• @plypaul (#2066, #2055, #2056, #2064, #2065, #2075, #2076, #2084, #2085, #2088, #2102, #2051, #2105, #2108)

MetricFlow 0.211.0 - May 11, 2026

Features

• Return results from OSI<>MSI converters as a ConverterResult object (#2031)
• Add support for Python 3.14 for metricflow package (#1916)
• Allow multiple --where arguments in the CLI (#2050)

Fixes

• Isolate mypy cache between metricflow / dbt-metricflow (#2046)

Under the Hood

• Run lint / tests for dbt-metricflow in a separate environment (#2039)
• Port dbt-metricflow package CI tests (#1933)
• Update dbt-metricflow package tests to check log file (#1934)
• Initial step for release automation tool (#2040)
• Add other steps for release automation tool (#2042)
• Assorted refinements to the release tool (#2045)
• Add retries to test_format_report_to_text_table (#2047)

Dependencies

• Remove graphviz dependency from dbt-metricflow (#2038)
• Update DuckDB dev dependency to >= 1.5 (#2051)

Contributors

• @QMalcolm (#2031)
• @ash2shukla (#1916)
• @plypaul (#2050, #2046, #2039, #1933, #1934, #2040, #2042, #2045, #2047, #2038, #2051)

MetricFlow 0.210.0 - April 24, 2026

Breaking Changes

• Remove MetricFlowEngine.get_measures_for_metrics (#1881)
• License Change - Version 0.209.0 and greater is covered by the Apache 2.0 license. (#1905)

Features

• Add new transformations to production from dsi that produce metrics from old-style measures. (#387)
• Generate nested CTEs to simplify SQL (#1992)
• Add initial implementation of OSI converters (#2017)

Fixes

• Don't error for lack of time dimensions in manfest (#1848)
• Pin to the latest non-dev release of dbt-semantic-interfaces. (#1854)
• Use node_relation to render time spine table with proper quoting. (#1875)
• Fixes a bug related to leaving out metric values in offset metrics, specifically if the queried grain is smaller than the offset grain. (#1910)
• Properly apply time constraints on agg time dimensions for cumulative metrics. (#1910)
• Fixes a bug causing errors for join_to_timespine metrics queried with date part. (#1919)
• Add dunder prefix to column aliases for simple-metric inputs (#1938)
• Render simple-metric inputs without a dunder prefix for the WHERE filter (#1941)
• Improve handling of invalid metrics in metadata methods of MetricFlowEngine (#1949)
• Fixes an issue where metric-level YAML filters are not applied for cumulative & conversion metrics. (#1950)
• Fix logging setup in the CLI (#1932)
• Fixes a bug where time dimensions utilizing the default time grain raise an error. (#1955)
• Add memoization to resolve_available_items to prevent repeated expensive DAG traversals during query resolution with invalid group-by items (#1964)
• Fix optimization of queries containing metrics withfill_nulls_with set (#1963)
• Improve CTE generation via caching in ComputeMetricsBranchCombiner (#1986)
• Prevent base-grain time dimensions from leaking into time-offset metric output (#2004)
• Fix check for aggregation time dimensions in filters (#2012)
• Fix bug with filters applied before aggregation in time-offset metrics (#2016)
• Fix queries mixing aliased and non-aliased versions of the same dimension (#2025)

Docs

• Update help text for mf query options (#1815)
• Improve OSS contribution standards in CONTRIBUTING.md (#1996)

Under the Hood

• Add tests for the filtering of AnnotatedSpecLinkableElementSet (#1864)
• Remove LegacyLinkableSpecResolver (#1865)
• Consolidate measure / metric methods of GroupByItemSetResolver (#1871)
• Add test for group-by items using the cyclic manifest (#1869)
• Add workflow to check changelog files (#1847)
• Remove LinkableElementSet (#1866)
• Rename classes for group-by items (#1870)
• Consolidate measure-related operations into MeasureLookup (#1868)
• Consolidate measure / metric methods of MetricLookup (#1872)
• Assorted fixes for GroupByItemSetFilter (#1873)
• Bump dependence on dbt-semantic-interfaces to 0.9.3.dev4 to get newest transformations code. (#387)
• Add SemanticGraphNodeTypedCollection (#1880)
• Update metricflow_semantics to migrate measures -> simple metrics (#1882)
• Update metricflow to migrate measures -> simple metrics (#1889)
• Add a test for MetricLookup. get_aggregation_time_dimension_specs() (#1890)
• Update SQL engine snapshots for the measures -> simple metrics migration (#1891)
• Remove measure-related functionality from MetricLookup (#1892)
• Remove deprecated measure-related classes (#1893)
• Update simple-metric generation in the synthetic manifest generator (#1894)
• Copy dbt-semantic-interfaces into the MetricFlow repo. (#1895)
• Mark tests from test_dataflow_to_sql_plan.py as DuckDB-Only (#1896)
• Remove SimpleMetricInputSpec.non_additive_dimension_spec (#1897)
• Renames for the measures -> simple metrics migration - Part 1 (#1898)
• Renames for the measures -> simple metrics migration - Part 2 (#1902)
• Renames for the measures -> simple metrics migration - Part 3 (#1903)
• Rename Metricflow* -> MetricFlow* (#1904)
• Remove assorted unused code (#1908)
• Move helper / utility methods to toolkit module (#1909)
• Update Cursor rules file to include linting + loading of additional rules (#1920)
• Move semantic-graph modules out of experimental (#1921)
• Remove case to reproduce date-part bug (#1922)
• Consolidate alias SQL generation to ComputeMetricsNode (#1936)
• Remove AggregateSimpleMetricInputsNode.alias_mapping (#1937)
• Filter out unneeded specs in dataflow plan before applying where filter. (#1944)
• Move CLI tests to dbt-metricflow package. Developers will need to run make test-include-slow to execute CLI tests locally, and will need to run hatch -v run dev-env:pre-commit clean to pick up the relevant config changes for linting. (#1948)
• Multiprocess explain-SQL test framework (#1951)
• Support explain-SQL tests using external manifests (#1952)
• Add explain-SQL test using all metric / group-by item pairs (#1953)
• Add a test for a query that includes a time-offset metric and metric_time__alien_day (#1954)
• Test optimization of queries containing metrics withfill_nulls_with set (#1962)
• Update ComputeMetricsNode to allow passthrough (#1972)
• Rename FilterElementsNode to SelectorNode (#1973)
• Assorted updates to DataflowPlanBuilder (#1976)
• Remove WhereFilterSpecSet (#1977)
• Replace PydanticMetricTimeWindow fields with immutable equivalent (#1978)
• Rename WhereConstraintNode to WhereFilterNode for consistency (#1979)
• Improve rendering of multiple WHERE filters (#1980)
• Remove LinklessEntitySpec (#1981)
• Assorted updates to ordered set and graph classes (#1982)
• Add .create() initializer to spec / request classes (#1983)
• Use a graph to model metric evaluation for a query (#1984)
• Add DFS metric evaluation planner (#1985)
• Update DataflowPlanBuilder to use DFS metric evaluation plan (#1989)
• Update metric evaluation planner tests to include SQL (#1990)
• Add passthrough metric evaluation planner (#1991)
• Add DataflowPlanOptionSet to group build options (#1995)
• Add PASSTHROUGH_METRIC_EVALUATION as an optimizer option (#1994)
• Add tests for nested offset metric queries with custom time grains (#1988)
• Fold metricflow-semantics into metricflow (#2000)
• Sync dbt-semantic-intefaces to metricflow-semantic-interfaces in metricflow (#2001)
• Begin depending on metricflow-semantic-interfaces instead of dbt-semantic-interfaces (#2002)
• Remove unused code in dataflow_plan_builder.py (#2003)
• Move directory anchor to toolkit module (#2006)
• Add a helper to consolidate operations for time-offset metrics (#2008)
• Add tests for bugs with filter application in time-offset metrics (#2007)
• Added copilot instructions to improve AI code review support. (#2011)
• Simplify metricflow dependencies (#2015)
• Add a test case for time-offset metric with non-queried item in the filter (#2009)
• Update ruff.toml and AGENTS.md for Python 3.10 (#2022)
• Streamline alias node addition in DataflowPlanBuilder (#2023)
• Move alias rendering tests to a separate file (#2024)
• Allow order-by items to omit the alias (#2030)

Dependencies

• Update requirement for dependency more-itertools to include newest version (#1879)
• Update to dbt-semantic-interfaces==0.9.4.dev0 (#1889)
• Bumping upperbound range for dbt-semantic-interfaces in metricflow-semantics
• Add SqlAlchemy based SqlClient for test execution. This alters the developer environment to include SqlAlchemy dependencies. (#1966)
• Remove dbt dependencies from Metricflow development packages. This will require an environment refresh across metricflow and dbt-metricflow. (#1967)
• Expand dbt-core support to <1.12
• Update supported Python versions to >=3.10, <3.14 (#2020)

Contributors

• @MatthijsKok (#1879)
• @QMalcolm (#2017, #2000, #2001, #2002)
• @TTMichaelA
• @WilliamDee
• @b-per (#1815)
• @courtneyholcomb (#1905, #1848, #1854, #1875, #1910, #1910, #1919, #1950, #1955, #387, #1895, #1944)
• @plypaul (#1881, #1992, #1938, #1941, #1949, #1932, #1963, #1986, #2004, #2012, #2016, #2025, #1864, #1865, #1871, #1869, #1847, #1866, #1870, #1868, #1872, #1873, #1880, #1882, #1889, #1890, #1891, #1892, #1893, #1894, #1896, #1897, #1898, #1902, #1903, #1904, #1908, #1909, #1920, #1921, #1922, #1936, #1937, #1951, #1952, #1953, #1954, #1962, #1972, #1973, #1976, #1977, #1978, #1979, #1980, #1981, #1982, #1983, #1984, #1985, #1989, #1990, #1991, #1995, #1994, #1988, #2003, #2006, #2008, #2007, #2015, #2009, #2022, #2023, #2024, #2030, #1889, #2020)
• @theyostalservice (#387, #1996, #387, #2011)
• @tlento (#1948, #1966, #1967)
• @wiggzz (#1964)

Releases MetricFlow with an Apache 2.0 license.

Note that dbt-semantic-interfaces is currently pinned to a development version, which may cause issues for some installers. This will be resolved soon.

What's Changed

• Bump dbt-metricflow version by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1860
• Bump to new dev version by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1859
• Bump to a new dev version of dbt-metricflow by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1861
• Bug fix: don't error if there are no time dims in manifest by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1862
• Bump to new DSI dev version (again) by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1863
• Bump dsi version to allow for 'is_private' on metrics from mantle by @theyostalservice in https://github.com/dbt-labs/metricflow/pull/1867
• Add tests for the filtering of AnnotatedSpecLinkableElementSet by @plypaul in https://github.com/dbt-labs/metricflow/pull/1864
• Remove LegacyLinkableSpecResolver by @plypaul in https://github.com/dbt-labs/metricflow/pull/1865
• Remove LinkableElementSet by @plypaul in https://github.com/dbt-labs/metricflow/pull/1866
• Consolidate measure-related operations into MeasureLookup by @plypaul in https://github.com/dbt-labs/metricflow/pull/1868
• Add test for group-by items using the cyclic manifest by @plypaul in https://github.com/dbt-labs/metricflow/pull/1869
• Rename classes for group-by items by @plypaul in https://github.com/dbt-labs/metricflow/pull/1870
• Pin version more tightly while we resolve test failures by @theyostalservice in https://github.com/dbt-labs/metricflow/pull/1874
• Use node_relation to render time spine table SQL by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1875
• Consolidate measure / metric methods of GroupByItemSetResolver by @plypaul in https://github.com/dbt-labs/metricflow/pull/1871
• Consolidate measure / metric methods of MetricLookup by @plypaul in https://github.com/dbt-labs/metricflow/pull/1872
• Bump DSI Version by @theyostalservice in https://github.com/dbt-labs/metricflow/pull/1876
• Get MF using the new dsi transformations by @theyostalservice in https://github.com/dbt-labs/metricflow/pull/1877
• Assorted fixes for GroupByItemSetFilter by @plypaul in https://github.com/dbt-labs/metricflow/pull/1873
• Enable DimensionPattern without time dimensions by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1883
• Add SemanticGraphNodeTypedCollection by @plypaul in https://github.com/dbt-labs/metricflow/pull/1880
• Remove MetricFlowEngine.get_measures_for_metrics by @plypaul in https://github.com/dbt-labs/metricflow/pull/1881
• Update metricflow_semantics to migrate measures -> simple metrics by @plypaul in https://github.com/dbt-labs/metricflow/pull/1882
• Update metricflow to migrate measures -> simple metrics by @plypaul in https://github.com/dbt-labs/metricflow/pull/1889
• Add a test for MetricLookup. get_aggregation_time_dimension_specs() by @plypaul in https://github.com/dbt-labs/metricflow/pull/1890
• Update SQL engine snapshots for the measures -> simple metrics migration by @plypaul in https://github.com/dbt-labs/metricflow/pull/1891
• Remove measure-related functionality from MetricLookup by @plypaul in https://github.com/dbt-labs/metricflow/pull/1892
• Remove deprecated measure-related classes by @plypaul in https://github.com/dbt-labs/metricflow/pull/1893
• Update simple-metric generation in the synthetic manifest generator by @plypaul in https://github.com/dbt-labs/metricflow/pull/1894
• Update help to provide examples to AI agents by @b-per in https://github.com/dbt-labs/metricflow/pull/1815
• Update requirement for dependency more-itertools to include newest version by @MatthijsKok in https://github.com/dbt-labs/metricflow/pull/1879
• Mark tests from test_dataflow_to_sql_plan.py as DuckDB-Only by @plypaul in https://github.com/dbt-labs/metricflow/pull/1896
• Remove SimpleMetricInputSpec.non_additive_dimension_spec by @plypaul in https://github.com/dbt-labs/metricflow/pull/1897
• Renames for the measures -> simple metrics migration - Part 1 by @plypaul in https://github.com/dbt-labs/metricflow/pull/1898
• Renames for the measures -> simple metrics migration - Part 2 by @plypaul in https://github.com/dbt-labs/metricflow/pull/1902
• Renames for the measures -> simple metrics migration - Part 3 by @plypaul in https://github.com/dbt-labs/metricflow/pull/1903
• Sync DSI into MF by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1895
• Rename Metricflow* -> MetricFlow* by @plypaul in https://github.com/dbt-labs/metricflow/pull/1904
• Change License to Apache 2.0 by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1905

New Contributors

• @b-per made their first contribution in https://github.com/dbt-labs/metricflow/pull/1815
• @MatthijsKok made their first contribution in https://github.com/dbt-labs/metricflow/pull/1879

Full Changelog: https://github.com/dbt-labs/metricflow/compare/v0.208.1...v0.209.0

What's Changed

• Update metricflow to 0.208.1.dev0 by @plypaul in https://github.com/dbt-labs/metricflow/pull/1844
• Release dbt-metricflow==0.10.0 by @plypaul in https://github.com/dbt-labs/metricflow/pull/1845
• Update dbt-metricflow to 0.10.1.dev0 by @plypaul in https://github.com/dbt-labs/metricflow/pull/1846
• Add workflow to check changelog files by @plypaul in https://github.com/dbt-labs/metricflow/pull/1847
• Update offset implementation by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1826
• Cleanup: fix duckdb version + remove accidental commenting by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1856
• Pin to a non-dev version of DSI for release by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1854
• Create version 0.208.1 by @courtneyholcomb in https://github.com/dbt-labs/metricflow/pull/1855

Full Changelog: https://github.com/dbt-labs/metricflow/compare/v0.208.0...v0.208.1

MetricFlow 0.208.0 - September 11, 2025

Features

• Support for custom offset windows. (#1584)
• Support for multiple time spines in one query. (#1644)
• Allow bypassing the group by when making queries without metrics. (#1720)
• Support aliases for dimensions and entities. (#1727)
• Support for order_by and limit on saved queries (#1759)
• Expose semantic_model(s) on Metrics and Dimensions in API (#1776)
• Support ordering dimensions by semantic model name" (#1778)
• Add new CLI command 'mf list saved-queries' to list all saved queries with their descriptions (#1787)
• Improve engine initialization speed via semantic graph (#1835)

Fixes

• Add config to get_measures_for_metrics response (#1606)
• Compatibility Issue with dbt-core 1.9.0 and dbt-metricflow 0.7.1. (#1589)
• dbt-core dependency issue with metricflow==0.207.0. (#1632)
• Remove semantic_manifest.json from the tutorial project (#1704)
• Remove trailing comma when pretty-formatting list (#1735)
• Fix error message with empty queries (#1740)
• Fix exception propagation in SQL generation (#1747)
• Fix ambiguity error for time dimensions in Dimension Jinja block (#1772)
• Ensure agg_time_dimension is lowercased (#1773)
• Fix error message in no_common_items.py (#1795)
• Fix ambiguous-join-path detection for UNIQUE entities (#1835)

Under the Hood

• Add properties to LazyFormat for custom logging handlers (#1713)
• Synthetic manifests for performance tests (#1495)
• Add support for index object to improve MF engine initialization times. (#1715)
• Use option object for mf_pformat (#1731)
• Provide context in MetricFlowPrettyFormattable.pretty_format() (#1733)
• Use {} for pretty-formatting Set (#1734)
• Add include_underscore_prefix_fields option to mf_pformat (#1736)
• Add pretty_format_object_by_parts() to pretty formatter (#1738)
• Add test to check the error message for empty queries (#1739)
• Update SequentialIdGenerator to support async methods (#1741)
• Generate a SELECT statement for sink nodes in a dataflow plan (#1743)
• Update SelectColumnSet fields to tuples (#1744)
• Add MetricQuerySpec.spec_output_order (#1745)
• Update engine interface to order output columns by query inputs (#1746)
• Use output from the click invocation to check test results (#1749)
• Handle order_output_columns_by_input_order for filtered metrics (#1753)
• Rename mf_test_configuration -> snapshot_configuration (#1750)
• Consolidate dev dependencies of metricflow-semantics and metricflow (#1751)
• Add handling of Path objects in mf_pformat() (#1752)
• Implement Sized for WhereFilterSpecSet (#1756)
• Skip rendering of the table alias in SQL if not needed (#1757)
• Replace Singleton with @singleton_dataclass() (#1761)
• Assorted improvements to snapshot methods (#1762)
• Implement Mergeable for PrettyFormatOption (#1763)
• Add base classes to model a directed graph (#1764)
• Add formatter to display graphs in DOT notation. (#1766)
• Add formatter to display graphs in DOT notation (#1766)
• Assorted fixes for graph-related classes (#1782)
• Remove predicate pushdown optimizer for now (#1783)
• Update the snapshot format for LinkableElementSet (#1784)
• Add interfaces for LinkableElementSet / LinkableSpecResolver (#1785)
• Add fast lookup for semantic-manifest objects (#1789)
• Add a helper for writing timeit-based performance tests (#1788)
• Cache predecessors / successors in graphs (#1790)
• Add semantic-graph node classes (#1791)
• Migrate back to Singleton for simplicity / performance (#1793)
• Add semantic-graph edge classes (#1794)
• Add subgraph generator for measures (#1796)
• Add subgraph generator for modeling joins (#1798)
• Add subgraph generator for categorical dimensions (#1799)
• Add subgraph generator for configured-entity keys (#1800)
• Add subgraph generator for metrics (#1802)
• Add subgraph generator for time-related elements (#1801)
• Add graph path / pathfinder classes (#1803)
• Add path weight-function for the semantic graph (#1804)
• Add trie-like data structure for dunder names (#1805)
• Add semantic-graph-based resolver for simple group-by items (#1806)
• Add semantic-graph-based resolver for group-by metrics (#1807)
• Add an implementation of LinkableSpecResolver using the semantic-graph (#1808)
• Add performance tests for the semantic-graph-based resolver (#1809)
• Add use_semantic_graph flag to SemanticManifestLookup (#1812)
• Add query-parser tester and additional cases for SCDs (#1814)
• Update error handling for simple_dimensions_for_metrics (#1816)
• Minor fixes for semantic manifests in test cases (#1818)
• Add text-table formatter for SessionReport (#1819)
• Assorted minor fixes / improvements (#1820)
• Switch back to using minimum time grain from models (#1822)
• Migrate correctness tests for the semantic-graph-based resolver (#1833)
• Migrate performance tests for the semantic-graph-based resolver (#1834)

Dependencies

• Remove version requirement for dbt adapters in dbt-metricflow (#1837)

Contributors

• @DevonFulcher (#1606)
• @courtneyholcomb (#1584, #1644, #1720, #1727, #1759, #1776, #1778, #1772, #1773)
• @kiwamizamurai (#1787)
• @plypaul (#1835, #1589, #1632, #1704, #1735, #1740, #1747, #1795, #1835, #1713, #1495, #1715, #1731, #1733, #1734, #1736, #1738, #1739, #1741, #1743, #1744, #1745, #1746, #1749, #1753, #1750, #1751, #1752, #1756, #1757, #1761, #1762, #1763, #1764, #1766, #1766, #1782, #1783, #1784, #1785, #1789, #1788, #1790, #1791, #1793, #1794, #1796, #1798, #1799, #1800, #1802, #1801, #1803, #1804, #1805, #1806, #1807, #1808, #1809, #1812, #1814, #1816, #1818, #1819, #1820, #1822, #1833, #1834, #1837)

Features

• Allow querying SCDs without metric_time. (#1621)
• Add --quiet option to the query CLI command. (#1554)
• Specify DB file path in tutorial-project profile (#1692)
• Add support for DBT_PROFILES_DIR / DBT_PROJECT_DIR in the CLI (#1702)
• Add semantic manifest artifact context to error messages (#1708)

Fixes

• Update tutorial project to use ref() (#1691)
• Address issues with the display of numeric types (#1699)
• Address display of None in the output of mf query (#1700)
• Address display of whitespace-padded strings in the output of mf query (#1701)
• Address intermittently missing CSV output file (#1709)
• Configure pytest to skip scanning snapshots directory (#1710)
• Fix issue counter when generating error messages. (#1708)

Under the Hood

• Use snapshots in CLI tests. (#1690)
• Allow CliConfiguration to be loaded from specified paths (#1693)
• Remove dbt project metadata dependency in tutorial project generation (#1694)
• Avoid reinitialization of CLIConfiguration (#1697)
• Add process-isolated CLI runner for tests (#1695)
• Migrate CLI tests to use the process-isolated CLI runner (#1696)

Contributors

• @courtneyholcomb (#1621)
• @plypaul (#1554, #1692, #1708, #1691, #1699, #1700, #1701, #1709, #1710, #1708, #1690, #1693, #1694, #1697, #1695, #1696)

Changes from 0.207.2:

This release includes a number of a number of assorted fixes and updates that were backported from main. It includes some updates to enable CTEs by default.

MetricFlow 0.207.2 - February 21, 2025

Features

• Allow setting aliases for queried metrics (#1573)

Fixes

• Always treat metric_time and the agg_time_dimension the same in the JoinToTimeSpineNode. (#1541)
• Apply time constraints after time offsets to avoid filtering out values that will change later in the query. (#1544)
• Update mf tutorial flow to always create / use the sample dbt project. (#1651)

Contributors

• @courtneyholcomb (#1541, #1544)
• @plypaul (#1651)
• @serramatutu (#1573)

Changes from 0.206.0:

Note: this release is compatible with / requires dbt-core >= 1.9.0, < 1.10.0 and is cut from 5bb13511d36c6122527a1bd12de9d6e0707a9ddc. The prior version 0.207.0 on Pypi depended on a version of dbt-semantic-interfaces that was later than the versions supported in the latest official release of dbt-core (1.9.1 as of this note).

Breaking Changes

• Changes MetricFlowQueryRequest.where_constraint to where_constraints and now accepts a list (#1431)
• Require Python >=3.9 (#1470)
• Require dbt-core >= 1.9.0, < 1.10.0 (#1615 )

Features

• Enable predicate pushdown for categorical dimensions (#1011)
• Support sub-daily granularity options in SQL rendering for all supported SQL engines. (#1258)
• Adds a new dataflow plan node to re-aggregate metrics using window functions. Needed to calculate cumulative metrics at non-default granularities. (#1274)
• Build dataflow plan for cumulative metrics queried with non-default granularity. (#1281)
• Remove restriction on querying non-default granularities with cumulative metrics. (#1282)
• Enable predicate pushdown optimization by default for all callers (#1011)
• Use Metric.time_granularity to resolve metric_time. (#1310)
• Support multiple time spines with different granularities. (#1348)
• Enable sub-daily queries without metrics. (#1359)
• Enable sub-daily time constraints. (#1367)
• Support combining AggregateMeasuresNodes where metric input measures have aliases, so long as there are no duplicates. (#1375)
• Handle custom granularities in DataflowPlan. (#1382)
• Support custom granularities in query parsing. (#1413)
• Support conversion metrics queried with custom granularities. (#1475)
• Basic support for join_to_timespine metrics with custom grain in the group by. (#1505)
• Use CTEs instead of sub-queries in generated SQL. (#1040)

Fixes

• When querying multiple agg time or metric time dimensions with a cumulative metric, select all of them from the time spine table. (#1271)
• Remove extraneous where filter subqueries added by predicate pushdown (#1011)
• Add Column header to the exported CSV from query command
• Allow metrics with matching input measures where one is cumulative and one is not. (#1374)
• Fixes bug where conversion metric query fails when filter with base semantic model's dimension is provided (#1210)
• Bug fix: ensure that granularity requested for non-additive dimension is respected. (#1383)
• Bug fix: when querying a join_to_timespine metric with a metric_time filter that is not included in the group by, unexpected output rows were included. (#1450)
• Remove unnecessary group bys that make queries less efficient. (#1453)
• Add new validation that checks for SCDs in the join path to make grouping by metric_time required in this case. (#1451)
• Make ID generation thread-safe (#1473)
• Prevent SourceScanOptimizer from combining nodes that use the same input metric alias in different derived metrics (#1494)
• Fix mf tutorial experience. (#1631)
• Compatibility Issue with dbt-core 1.9.0 and dbt-metricflow 0.7.1. (#1589)
• dbt-core dependency issue with metricflow==0.207.0. (#1632)

Under the Hood

• Add test coverage for more filter + join interactions (#1240)
• Add dataflow plan optimizer to replace build-time predicate pushdown (#1011)
• Added filtering for DWH validation tasks and saved query support (#1271)
• Refine subquery ID generation. This may result in changing subquery ids for rendered SQL. (#1280)
• Move categorical dimension predicate pushdown to DataflowPlanOptimizer (#1011)
• Consume cumulative-specific metric type params from new cumulative_type_params field. (#1293)

Dependencies

• Allow pydantic 2.x installations (#1299)

Contributors

• @WilliamDee (#1210, #1271)
• @WilliamDee,courtneyholcomb (#1431)
• @courtneyholcomb (#1258, #1274, #1281, #1282, #1310, #1348, #1359, #1367, #1375, #1382, #1413, #1475, #1505, #1271, #1374, #1383, #1450, #1453, #1293)
• @plypaul (#1470, #1040, #1473, #1631, #1589, #1632)
• @saurabh0402
• @serramatutu (#1451, #1494)
• @tlento (#1011, #1011, #1011, #1240, #1011, #1280, #1011, #1299)

Breaking Changes

• Changes MetricFlowQueryRequest.where_constraint to where_constraints and now accepts a list (#1431)
• Require Python >=3.9 (#1470)

Features

• Enable predicate pushdown for categorical dimensions (#1011)
• Support sub-daily granularity options in SQL rendering for all supported SQL engines. (#1258)
• Adds a new dataflow plan node to re-aggregate metrics using window functions. Needed to calculate cumulative metrics at non-default granularities. (#1274)
• Build dataflow plan for cumulative metrics queried with non-default granularity. (#1281)
• Remove restriction on querying non-default granularities with cumulative metrics. (#1282)
• Enable predicate pushdown optimization by default for all callers (#1011)
• Use Metric.time_granularity to resolve metric_time. (#1310)
• Support multiple time spines with different granularities. (#1348)
• Enable sub-daily queries without metrics. (#1359)
• Enable sub-daily time constraints. (#1367)
• Support combining AggregateMeasuresNodes where metric input measures have aliases, so long as there are no duplicates. (#1375)
• Handle custom granularities in DataflowPlan. (#1382)
• Support custom granularities in query parsing. (#1413)
• Support conversion metrics queried with custom granularities. (#1475)
• Basic support for join_to_timespine metrics with custom grain in the group by. (#1505)
• Use CTEs instead of sub-queries in generated SQL. (#1040)
• Add meta to dimensions, entities, and measures
• Adds tags to SavedQueries
• Allow setting aliases for queried metrics (#1573)

Fixes

• When querying multiple agg time or metric time dimensions with a cumulative metric, select all of them from the time spine table. (#1271)
• Remove extraneous where filter subqueries added by predicate pushdown (#1011)
• Add Column header to the exported CSV from query command
• Allow metrics with matching input measures where one is cumulative and one is not. (#1374)
• Fixes bug where conversion metric query fails when filter with base semantic model's dimension is provided (#1210)
• Bug fix: ensure that granularity requested for non-additive dimension is respected. (#1383)
• Bug fix: when querying a join_to_timespine metric with a metric_time filter that is not included in the group by, unexpected output rows were included. (#1450)
• Remove unnecessary group bys that make queries less efficient. (#1453)
• Add new validation that checks for SCDs in the join path to make grouping by metric_time required in this case. (#1451)
• Make ID generation thread-safe (#1473)
• Prevent SourceScanOptimizer from combining nodes that use the same input metric alias in different derived metrics (#1494)
• Always treat metric_time and the agg_time_dimension the same in the JoinToTimeSpineNode. (#1541)
• Apply time constraints after time offsets to avoid filtering out values that will change later in the query. (#1544)

Under the Hood

• Add test coverage for more filter + join interactions (#1240)
• Add dataflow plan optimizer to replace build-time predicate pushdown (#1011)
• Added filtering for DWH validation tasks and saved query support (#1271)
• Refine subquery ID generation. This may result in changing subquery ids for rendered SQL. (#1280)
• Move categorical dimension predicate pushdown to DataflowPlanOptimizer (#1011)
• Consume cumulative-specific metric type params from new cumulative_type_params field. (#1293)

Dependencies

• Allow pydantic 2.x installations (#1299)

Contributors

• @DevonFulcher
• @WilliamDee (#1210, #1271)
• @WilliamDee,courtneyholcomb (#1431)
• @courtneyholcomb (#1258, #1274, #1281, #1282, #1310, #1348, #1359, #1367, #1375, #1382, #1413, #1475, #1505, #1271, #1374, #1383, #1450, #1453, #1541, #1544, #1293)
• @plypaul (#1470, #1040, #1473)
• @saurabh0402
• @serramatutu (#1573, #1451, #1494)
• @theyostalservice
• @tlento (#1011, #1011, #1011, #1240, #1011, #1280, #1011, #1299)

MetricFlow 0.206.0 - June 11, 2024

This release requires dbt-core version 1.8. The most important breaking change here will affect installation of the MetricFlow CLI - any MetricFlow CLI users should install dbt-metricflow to pick up the latest CLI updates. This was a necessary step in the process of decoupling the main MetricFlow library from dbt-core's minor version release cycle. Cloud CLI users are not affected.

Notable improvements include the ability to use metric values as filter expressions and some fixes for strange filter behaviors on time spine joins.

Breaking Changes

• Remove unsupported legacy MetricFlowClient APIs (#1094)
• Move MetricFlow CLI to dbt-metricflow package (#1090)

Features

• Allow metrics in filters for metrics and metric queries. (#740)
• Enable metric filters for distinct values queries. (#1107)
• List all dimensions for the semantic manifest. (#1142)
• Add a Dependency Resolver for Saved Queries (#1155)
• Add support for Python 3.12 (#1065)
• Update dbt-metricflow dependencies to use dbt* 1.8 packages (#1243)

Fixes

• Enable filtering by metrics in the same semantic model as queried metrics. (#1115)
• Improve error messages for dataflow plan failures. (#1118)
• Remove redundant entity names like 'listing__listing' from suggested group bys. (#1130)
• For metrics that join to time spine, apply post-join filters only for specs that are in the group by. (#1119)

Under the Hood

• Clean up files included in MetricFlow package distribution (#1092)
• Move MetricFlow tests to repository root (#1088)
• Create metricflow-semantics package. (#1150)
• Make source semantic models available from DataflowPlanNode instances (#1218)
• Cache functions related to parsing group by options in order to improve query performance. (#1229)

Dependencies

• Update Ruff to 0.3.3 (#769)
• Update dbt-semantic-interfaces minimum version to 0.5.1 (#1104)

Contributors

• @courtneyholcomb (#740, #1107, #1142, #1115, #1118, #1130, #1119, #1229)
• @plypaul (#1155, #1065, #1243, #1150)
• @tlento (#1094, #1090, #1092, #1088, #1218, #769, #1104)

This release is an intermediate update to MetricFlow and can be used with existing dbt-core 1.7 installations. The breaking changes listed here will only affect users relying on any sql-comment tagging the MetricFlow CLI had been doing previously (e.g., the mf_rid_* comments).

Notable improvements include increased flexibility in querying the metric_time dimension and increased consistency in how we manage metrics requesting joins against a time spine for filling in missing values on a time axis.

MetricFlow 0.205.0 - February 29, 2024

Breaking Changes

• Remove SQL-Comment-Based Tags (#1034)

Features

• Enable querying metric_time without metrics. (#928)
• Enable querying cumulative metrics with their agg_time_dimension. (#1000)
• Enable offset metrics to be queried with agg_time_dimension. (#1006)
• Add Support for Consistent SQL Query Generation (#1020)

Fixes

• Validate that there are metrics or group by items in each query. (#1002)
• For measures that join to time spine, allow joining when agg_time_dimension is queried. (#1009)
• Join to time spine if requested for conversion metric input measures. (#1048)
• Enable querying offset metric with multiple agg_time_dimensions at once. Also fixes a bug when filtering by a different grain than the group by grain. (#1052, #1053)
• Bug fix: if measure joins to time spine, apply filters again after that join. (#1039)
• Improve error message for metrics/queries with missing inputs (#1051)

Docs

• change group-bys to group-by in the tutorial message

Under the Hood

• Add test for nested derived metric filter rendering bug fixed in 0.204.0 (#920)

Dependencies

• Remove unused numpy dependency (#984)
• Update Jinja2 past 3.1.3 to resolve CVE-2024-22195 (#1049)

Contributors

• @batou9150
• @courtneyholcomb (#928, #1000, #1006, #1002, #1009, #1048, #1052, #1053, #1039)
• @plypaul (#1034, #1020)
• @tlento (#1051, #920, #984, #1049)

To take full advantage of this release, please upgrade to dbt-core 1.7.4 or later. Earlier versions of dbt-core 1.7.x will continue to work with any config that does not include Conversion Metrics.

Notable improvements include:

• Support for Conversion Metrics
• Support for Trino (huge thanks to @sarbmeetka for the contribution!)
• A variety of important fixes and adjustments, particularly around time offset metrics

MetricFlow 0.204.0 - January 11, 2024

Features

• Add Trino support to the MetricFlow. (#207)
• Implemented date_part in where filter. (#None)
• Resolve Ambiguous Group-By-Items (#887)
• Support for Conversion Metrics (#252)
• Add a Query Validation Rule for Repeated Metrics in a Query (#943)
• Expose label on Metric & Dimension for use in APIs. (#956)

Fixes

• Apply time offset for nested dervied & ratio metrics (#882)
• Fix Incorrect SQL Column Name Rendering for WhereConstraintNode (#908)
• Unable To Satisfy Query Error with Cumulative Metrics in Saved Queries (#917)
• Fixes a bug in dimension-only queries where the filter column is removed before the filter has been applied. (#923)
• Bug fix: Keep where constraint column until used for nested derived offset metric queries. (#930)
• Fixes incorrect time constraint applied to derived offset metrics. (#925)
• Remove default time constraint for queries with cumulative metrics. (#917)
• Return exit code 1 for failed validations (#867)
• Optimizer Does Not Deduplicate Common Metrics (#941)
• Duplicate input measures after combiner optimizer (#969)

Under the Hood

• Test to ensure Dimension and TimeDimension syntax are identical in the case of time dimensions
• Fixed typo in error message

Dependencies

• Remove unnecessary MarkupSafe dependency (#950)

Contributors

• @DevonFulcher
• @WilliamDee (#252, #867, #969)
• @courtneyholcomb (#956, #882, #923, #930, #925)
• @plypaul (#887, #943, #908, #917, #917, #941)
• @sarbmeetka (https://github.com/sarbmeetka) (#207)
• @tlento (#950)

MetricFlow 0.203.1 - November 15, 2023

Fixes

• Fix error in cumulative metric output when start-time and end-time are specified (#869)

Dependencies

• Remove Rudderstack client and associated dependencies (#866)
• Relax version pin on typing extensions to allow >=4.4, <5 (#875)

Contributors

• @tlento (#869, #866, #875)

This release requires an upgrade to dbt core 1.7 , which is now the minimum requirement for future minor version updates to MetricFlow.

Notable improvements include:

• Support for saved queries
• Fixes for issues where time granularity was not being applied to columns with finer-grained input than what was listed in the config. This may cause performance regressions for users of partitioned datasets in certain engines, which we are committed to resolving.
• Support for configuring a way to fill null value measure outputs to prevent implicit null filtering.

Complete changelog follows. Please take note of the breaking changes.

MetricFlow 0.203.0 - November 13, 2023

Breaking Changes

• Use FULL OUTER JOIN to combine input metrics for derived metrics. This is a change from using INNER JOIN and may result in changes in output. (#842)
• Update Dependencies to Use dbt-semantic-interfaces~=0.4.0 (#846)

Features

• Enable DATE PART aggregation for time dimensions (#770)
• Support Saved Queries in MetricFlow (#765)
• Support for sort order in query interface (#None)
• Support for the Dimension(...).grain(...) syntax for the where parameter (#None)
• Support querying dimensions without metrics. (#804)
• Join to time spine and fill nulls when requested on metric input measures. (#759)
• Fill nulls for multi-metric queries (#850)

Fixes

• Removing methods and reordering parameters for Query Interface. (#None)
• Coerce time granularity to configured value to prevent finer-grained timestamps from causing unexpected query behavior (#714)
• Prioritize source nodes based on correct cost (#801)
• Enables case insensitivity for various query params. (#802)
• Ensure extract calls return consistent results across engines (#792)
• The --order param was being dropped from CLI saved queries. (#835)
• Fix query validation for metric_time requirements (#825)
• Use FULL OUTER JOIN for dimension-only queries. (#863)

Under the Hood

• A simple update to make the where filter query parameter objects more accurate (#None)
• Expose underlying where clause error message (#None)
• Remove query interface and depend on DSI protocol instead (#None)
• re-categorize TypeErrors that arise from create_from_where_filter into InvalidQueryException (#None)
• Add the ability to use distinct select in sql nodes (#None)
• Removed DatePart Enum and change imports to depend on DSI version instead. (#None)

Dependencies

• Update to dbt-semantic-interfaces~=0.3.0. (#809)
• Update typing-extensions minimum version to 4.4 (#823)
• Update dbt dependencies to ~=1.7.0 (#860)

Contributors

• @DevonFulcher
• @WilliamDee
• @courtneyholcomb (#842, #770, #804, #759, #850, #801, #802, #835, #863)
• @plypaul (#846, #765, #809)
• @tlento (#714, #792, #825, #823, #860)

This release adds support for granularity adjustments in window offsets and fixes an issue with BigQuery granularity adjustments for YEAR level granularities.

BigQuery users take note - YEAR granularity now truncates to calendar year start (1st January), which was the original intention, rather than ISO year start, which is something like the Monday of the week containing the first Thursday of the year. This is now consistent with other engines.

MetricFlow 0.202.0 - September 06, 2023

Features

• Adds the option for users to specify group by parameters with object syntax matching the where/filter expressions. (#717)
• Expose measures for metrics on MFEngine with agg_time_dimension (#735)

Fixes

• Update dataflow plan to support different granularities with time offset metrics (#726)
• Removes unneeded JoinOverTimeRangeNode step from dataflow plan. (#743)
• Update BigQuery YEAR granularity truncation to use January 1st instead of ISOYEAR start (#755)

Dependencies

• Allow tabulate versions >= 0.8.9 (#762)

This release adds duckdb support and provides a partial fix for user-reported issues with partition pruning in BigQuery.

MetricFlow 0.201.0 - August 17, 2023

Features

• Add dbt-duckdb as a supported adapter and remove legacy DuckDB sql client (#583)

Fixes

• Remove barrier to partition pruning certain time partition filter predicates (#712)

Under the Hood

• Make duckdb the standard for all dev-env environment runs, including make test (#723)
• (#728)

Dependencies

• Update pandas to 1.5.x (#719)
• Relax version pins for MetricFlow dependencies (#720)

Contributors

• @courtneyholcomb (#728)
• @jwills (#583)
• @tlento (#712, #723, #719, #720)

This release represents a complete overhaul of MetricFlow targeted at a first class integration with dbt! Complete changelog below:

MetricFlow 0.200.0 - August 02, 2023

Breaking Changes

• License Change - Version 0 to 0.140.0 was covered by the Affero GPL license. Version 0.150.0 and greater is covered by the BSL license. (#465)
• Removing time_format from DimensionTypeParams (#494)
• Use Templates For Defining Metric Filters (#505)
• Rename Metric.constraint to Metric.filter (#511)
• Deprecate and refactor CLI commands
• Removes async query and query cancel methods from SqlClient protocols (#577)
• Remove time spine introspection and table creation, which may break cumulative metric queries (#592)
• Remove SqlEngineAttributes construct from SqlClient interface in favor of dialect rendering and engine type properties (#577)
• CLI needs to be ran in a dbt project root directory
• Remove expr & ratio metrics and bundle with derived metrics. (#504)
• explain_get_dimension_values & get_dimension_values take a list of metrics parameters
• Remove MetricFlow config file - all future configuration must originate with the dbt project (#624)
• Update to dbt-semantic-interfaces==0.1.0.dev8. (#634)
• Changed the --group-bys option in mf query to be --group-by
• Add Support for primary_entity in Semantic Models (#694)

Features

• Added new entity calls to CLI/MetricFlowEngine
• Script to Generate Snapshots for Supported SQL Engines. (#609)
• Add dbt adapter support for postgres and enable it for tests (#578)
• Use dbt adapter to run queries and warehouse validations from MetricFlow CLI (#624)
• Enable Snowflake queries in dbt <-> MetricFlow CLI integration (#579)
• Refactor mf tutorial to work alongside a dbt project.
• New package dbt-metricflow which bundles dbt-core and metricflow and dbt-adapters
• Add Support for Python 3.10 / 3.11 (#659)
• Include metric_time in List Dimensions Output Where Appropriate (#673)
• Enable support for Redshift queries in dbt-metricflow integration (#582)
• Enable Databricks support for the dbt-metricflow integration (#580)
• Enable support for BigQuery for dbt metricflow integration users (#581)

Fixes

• Removes MySQL from SqlEngine and SqlDialect options since it is not supported. (#0)
• Derived metrics were not respecting the constraint defined in the original input metric's definition.
• Fixes type error in BigQuerySqlExpressionRenderer (#536)
• Fix broken type signature for log_call decorator
• Apply transformations to dbt-generated serialized model to fix issue with query generation (#624)
• Improve error message rendering in MetricFlow CLI (#646)
• Added --version and fix manifest transformer rules for dbt-core-=1.6.0b8 (#650)
• Include granularity suffix on time dimension name rendering for all time dimension granularities
• Clean up list dimensions outputs

Under the Hood

• Adding Changie (#457)
• Ensure use of ValidationIssue instead of ValidationIssueType. ValidationIssueType was from a time before ValidationIssue classes had proper inheritance, and it's continued use was become problematic for typing.
• Removing model from the ModelValidator.validate return type. The model isn't altered, and thus doesn't need to be returned.
• Moving AggregationType enum into dbt-semantic-interfaces
• Moving errors relevant to dbt_semantic_interfaces to dbt_semantic_interfaces
• Migrating to RapidFuzz (#470)
• Matching dbt-core issue templates (#457)
• Removing the transform CLA (#450)
• Pinning dbt-core to 1.4 (#475)
• Removing YamlLint (#472)
• Add ObjectToReference class in preparation of removing the .reference calls (##463,, ##464)
• Moving all *Reference objects to dbt-semantic-interfaces.
• Add pytest flag to use a persistent source schema for faster repeat testing. (#482)
• Renamed instances of and related to Identifiers to Entities. (#dbt-semantic-interfaces#9)
• Improves typechecking coverage by updgrading to MyPy 0.942 and removing blanket ignore all imports setting (#536)
• Push mypy to run using local environment packages in pre-commit. Developers should always use a clean virtual environment to ensure consistency with CI. (#530, #536)
• Update mypy to 1.3.0 (#546)
• Migrate from Poetry -> Hatch for Project / Package Management (#549)
• Enable the ability to return only dimensions requested in the query, specifically used for dimension values queries.
• Raising a UnsupportedEngineFeatureError instead of a generic RuntimeError when a data platform doesn't support a feature
• Remove SqlIsolationLevel constructs and other vestigial remnants of defunct SqlClient features (#577)
• Raise a more specific exception when a Metric isn't found during linking.
• Update test environment configuration to allow for more streamlined dependencies
• Remove DDL and other unused methods from SqlClient protocol

Dependencies

• Switches MetricFlow SemanticManifest dependencies from the local dbt semantic interfaces package to the initial dev release (#540)
• Clean up unused dependencies, relax tabulate version pin (#545)
• Update dbt dependencies to support development on the new integration (#571)
• Move SQLAlchemy and SQL engine dependencies out of the production package (#672)
• Update dependencies and attribution file in preparation for 0.200.0 release (#703)

Contributors

• @DevonFulcher
• @QMalcolm
• @WilliamDee
• @callum-mcdata
• @courtneyholcomb
• @nhandel
• @plypaul
• @tlento