{"id":7147,"library":"dbt-metricflow","title":"dbt-metricflow","description":"dbt-metricflow is a Python package that bundles dbt-core, MetricFlow, and supported dbt adapters to provide a semantic layer for defining and managing metrics within a dbt project. It compiles metric definitions into reusable SQL, ensuring consistent analysis across data. Part of the Open Semantic Interchange (OSI) initiative, it simplifies metric governance and query generation. The current version is 0.11.0, with a release cadence tied to the underlying dbt-core and MetricFlow libraries, with the bundle aiming to ensure compatibility between them.","status":"active","version":"0.11.0","language":"en","source_language":"en","source_url":"https://github.com/dbt-labs/metricflow","tags":["dbt","semantic layer","metrics","data governance","analytics engineering","sql generation"],"install":[{"cmd":"pip install \"dbt-metricflow[adapter_package_name]\"","lang":"bash","label":"With a specific dbt adapter (e.g., dbt-snowflake)"},{"cmd":"pip install dbt-metricflow","lang":"bash","label":"For dbt Core users (without a specific adapter extra)"}],"dependencies":[{"reason":"Required Python version range.","package":"python","optional":false},{"reason":"dbt-metricflow bundles dbt-core to ensure compatibility for the semantic layer functionality. The specific dbt-core version is managed by the dbt-metricflow bundle.","package":"dbt-core","optional":false},{"reason":"Specific dbt adapters (e.g., dbt-snowflake, dbt-postgres) are required to connect to a data warehouse. These are installed as extras.","package":"dbt-adapter","optional":true},{"reason":"Optional for certain visualization features or advanced setups.","package":"graphviz","optional":true},{"reason":"Optional for certain local setups or specific database connections.","package":"postgresql","optional":true}],"imports":[{"note":"dbt-metricflow is largely a CLI-driven tool, extending dbt Core with semantic layer capabilities. Users interact with it through dbt CLI commands like `dbt sl list metrics` rather than importing Python classes for high-level operations.","symbol":"MetricFlow CLI commands","correct":"Interaction is primarily via the dbt CLI using 'dbt sl <command>' or 'mf <command>'. Direct Python API imports for end-user semantic layer querying are not the primary interaction model."}],"quickstart":{"code":"import subprocess\nimport os\n\n# This assumes a dbt project with semantic models and metrics defined is set up.\n# And dbt-metricflow (with an adapter) is installed in the environment.\n\n# Example: List available metrics in your dbt project\nprint(\"Listing dbt metrics...\")\nresult = subprocess.run(['dbt', 'sl', 'list', 'metrics'], capture_output=True, text=True, check=False)\nprint(result.stdout)\nif result.stderr:\n    print(f\"Error: {result.stderr}\")\n\n# Example: Validate your semantic layer configurations\nprint(\"Running dbt semantic layer health checks...\")\nresult = subprocess.run(['dbt', 'sl', 'health-check'], capture_output=True, text=True, check=False)\nprint(result.stdout)\nif result.stderr:\n    print(f\"Error: {result.stderr}\")\n","lang":"python","description":"This quickstart demonstrates how to interact with dbt-metricflow functionality through the `dbt sl` CLI commands using Python's `subprocess` module. This is the primary way users query and validate semantic layer definitions. Ensure you have a dbt project with semantic models and metrics configured, and dbt-metricflow (with an appropriate adapter) installed in your environment."},"warnings":[{"fix":"Use `pip install \"dbt-metricflow[adapter_package_name]\"` to ensure bundled and compatible versions are installed. Refer to the PyPI page for supported adapters and their versions.","message":"The `dbt-metricflow` package encapsulates `dbt-core`, `MetricFlow`, and `dbt-adapters` to manage version compatibility. Directly installing individual `dbt-core` or `MetricFlow` packages might lead to version conflicts due to dependencies on `dbt-semantic-interfaces`. Always prefer installing `dbt-metricflow[adapter]` to ensure a compatible bundle.","severity":"breaking","affected_versions":"<0.11.0"},{"fix":"Design your dbt models to pre-process data into a suitable format before defining semantic models and metrics, or structure your logic to avoid unsupported dbt functions within MetricFlow's scope. Check the official documentation for planned future support.","message":"MetricFlow (the underlying library) does not currently support dbt built-in functions or packages within semantic models. This can limit the complexity of logic directly expressible in metric definitions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you are installing `dbt-metricflow` to get the latest CLI features and updates. The `dbt sl` prefix for commands is generally recommended.","message":"Older versions of MetricFlow CLI users were required to install a separate `metricflow` package. As of MetricFlow 0.206.0, CLI updates are picked up by installing `dbt-metricflow`.","severity":"deprecated","affected_versions":"MetricFlow <0.206.0"},{"fix":"Avoid enabling the dbt semantic layer integration on the data connection if you require prepared statements for no-code filtering in tools like Hex. Consider alternative methods for syncing or managing schema in such cases.","message":"When integrating with tools like Hex, enabling the dbt semantic layer integration on the data connection can break prepared statements required for no-code filtering.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are using a Python version compatible with `dbt-metricflow` (currently `<3.13, >=3.9`). Try installing `dbt-metricflow` in a clean virtual environment: `python -m venv venv && source venv/bin/activate && pip install \"dbt-metricflow[your_adapter]\"`.","cause":"This error typically occurs when there's an incompatibility between the requested `dbt-core` version (implied by `dbt-metricflow`) and other installed packages or your Python environment.","error":"ERROR: Could not find a version that satisfies the requirement dbt-core==X.Y.Z (from dbt-metricflow)"},{"fix":"Verify that all tables and columns referenced in your dbt semantic project exist in your data warehouse. Refresh the schema of your data connection in the consuming tool. As a workaround, you can add column type annotations directly in your dimension definitions in YAML.","cause":"This issue arises when semantic projects reference columns that are not present in the target data warehouse's schema, or if the schema in the consuming tool (e.g., Hex) is out of date.","error":"Skipped column 'my_column' because it does not exist in the data connection's schema or type information is missing."},{"fix":"First, ensure `dbt-metricflow` is installed: `pip install \"dbt-metricflow[your_adapter]\"`. Confirm your dbt project is initialized and has semantic models defined. If running locally, check that your virtual environment is activated and `dbt` is accessible.","cause":"This indicates that either `dbt-metricflow` is not correctly installed, or the `dbt` executable is not in your system's PATH, or there's an issue with the dbt project setup. For dbt platform users, the `dbt sl` commands are embedded. For dbt Core users, `dbt-metricflow` must be installed.","error":"Command 'dbt sl list metrics' not found or failed."}]}