{"library":"metricflow","title":"MetricFlow","description":"MetricFlow is a Python library (version 0.209.0) developed by dbt Labs that serves as the engine for defining, querying, and serving metrics from dbt projects. It translates high-level metric definitions into reusable SQL and executes them against various data platforms. While it powers the dbt Semantic Layer, direct programmatic API usage is primarily for advanced scenarios like custom metric servers or programmatic SQL generation, rather than typical application-level querying. Releases typically align with dbt Core release cycles or critical updates for MetricFlow's standalone capabilities.","language":"python","status":"active","last_verified":"Thu Apr 16","install":{"commands":["pip install metricflow"],"cli":{"name":"metricflow","version":"sh: 1: metricflow: not found"}},"imports":["from metricflow.engine.metricflow_engine import MetricFlowEngine","from metricflow.config.metricflow_config import MetricFlowConfig","from metricflow.specs.query_specs import MetricFlowQuerySpec"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import os\nimport tempfile\nfrom pathlib import Path\nimport shutil\n\nfrom metricflow.engine.metricflow_engine import MetricFlowEngine\nfrom metricflow.config.metricflow_config import MetricFlowConfig\nfrom metricflow.connection.null_metricflow_connection import NullMetricFlowConnection\nfrom metricflow.specs.query_specs import MetricFlowQuerySpec, MetricTimeDimension\nfrom metricflow.specs.metric_request import MetricRequest\nfrom metricflow.specs.dimension_spec import DimensionSpec\n\n# This quickstart demonstrates programmatic SQL generation for a minimal semantic model.\n# Actual execution requires a configured database connection.\n\n# 1. Create a dummy dbt project directory with a semantic model YAML file\ntemp_dir = Path(tempfile.mkdtemp())\ndbt_project_dir = temp_dir / \"my_dbt_project\"\ndbt_project_dir.mkdir()\n(dbt_project_dir / \"dbt_project.yml\").write_text(\"\"\"\nname: 'my_dbt_project'\nversion: '1.0.0'\nconfig-version: 2\nprofile: 'default'\n\"\"\")\n\nmodels_dir = dbt_project_dir / \"models\"\nmodels_dir.mkdir()\n(models_dir / \"my_semantic_model.yml\").write_text(\"\"\"\nsemantic_models:\n  - name: my_transactions_semantic_model\n    description: \"Transactions data\"\n    entities:\n      - name: user_id\n        type: primary\n    measures:\n      - name: sum_amount\n        agg: sum\n        expr: amount\n    dimensions:\n      - name: transaction_date\n        type: time\n        expr: created_at\n        time_granularity: day\n    metrics:\n      - name: total_revenue\n        calculation_config:\n          measure: sum_amount\n\"\"\")\n\n# 2. Configure MetricFlow by pointing to the dbt project\nmf_config = MetricFlowConfig(\n    dbt_project_path=str(dbt_project_dir)\n)\n\n# 3. Use NullMetricFlowConnection for generating SQL plans without executing against a real DB\nmf_connection = NullMetricFlowConnection()\n\n# 4. Initialize MetricFlowEngine\nengine = MetricFlowEngine(mf_config, mf_connection)\n\n# 5. Define a query for the 'total_revenue' metric, grouped by user_id and day\nmetric_requests = [\n    MetricRequest(metric_name=\"total_revenue\")\n]\ntime_dimension = MetricTimeDimension(\n    grain=\"day\",\n    date_spec=('2023-01-01', '2023-01-31')\n)\nquery_spec = MetricFlowQuerySpec(\n    metric_requests=metric_requests,\n    group_by_dimensions=[DimensionSpec(element_name=\"user_id\")],\n    time_dimension=time_dimension\n)\n\nprint(\"\\n--- Generating SQL Query Plan ---\")\ntry:\n    # plan_query returns the SQL query string for the given spec\n    query_plan_result = engine.plan_query(query_spec)\n    print(\"Generated SQL Query:\")\n    print(query_plan_result.sql_query)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the temporary dbt project directory\n    shutil.rmtree(temp_dir)\n","lang":"python","description":"This quickstart demonstrates how to programmatically use MetricFlow to parse a semantic model definition and generate the corresponding SQL query. It sets up a minimal in-memory dbt project, configures the MetricFlow engine with a `NullMetricFlowConnection` to only generate a query plan (SQL) without execution. For actual data retrieval, replace `NullMetricFlowConnection` with a real database connection (e.g., `PostgresMetricFlowConnection`) and use `engine.query(query_spec)`.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}