dbt-metricflow

0.11.0 · active · verified Thu Apr 16

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.

Common errors

```
ERROR: Could not find a version that satisfies the requirement dbt-core==X.Y.Z (from dbt-metricflow)
```
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.

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]"`.
```
Skipped column 'my_column' because it does not exist in the data connection's schema or type information is missing.
```
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.

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.
```
Command 'dbt sl list metrics' not found or failed.
```
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.

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.

Warnings

breaking 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.
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.
gotcha 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.
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.
deprecated 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`.
Fix: Ensure you are installing `dbt-metricflow` to get the latest CLI features and updates. The `dbt sl` prefix for commands is generally recommended.
gotcha 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.
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.

Install

pip install "dbt-metricflow[adapter_package_name]" With a specific dbt adapter (e.g., dbt-snowflake)
pip install dbt-metricflow For dbt Core users (without a specific adapter extra)

Imports

MetricFlow CLI commands
```
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.
```
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.

Quickstart

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.

import subprocess
import os

# This assumes a dbt project with semantic models and metrics defined is set up.
# And dbt-metricflow (with an adapter) is installed in the environment.

# Example: List available metrics in your dbt project
print("Listing dbt metrics...")
result = subprocess.run(['dbt', 'sl', 'list', 'metrics'], capture_output=True, text=True, check=False)
print(result.stdout)
if result.stderr:
    print(f"Error: {result.stderr}")

# Example: Validate your semantic layer configurations
print("Running dbt semantic layer health checks...")
result = subprocess.run(['dbt', 'sl', 'health-check'], capture_output=True, text=True, check=False)
print(result.stdout)
if result.stderr:
    print(f"Error: {result.stderr}")

view raw JSON →