> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# dbt Metrics (MetricFlow)

> Let the agent answer from the MetricFlow metrics already defined in your dbt project, compiled exactly as dbt defines them.

If your dbt project defines metrics with the dbt Semantic Layer (MetricFlow), a [connected workspace](https://docs.upsolve.ai/ai-agent-builder/content-layer/overview.md) answers from them. A question about "spend by category last quarter" becomes a MetricFlow query for your `spend` metric grouped by `category`, so the number the agent gives is the number your dbt project defines — not a fresh SQL guess at what "spend" means.

## How it works

1. Your workflow's `dbt parse` writes `target/semantic_manifest.json`.
2. Each sync stores that manifest against the workspace version it publishes. The sync summary counts them (`13 tables, 24 metrics`).
3. When a question calls for a metric, the agent searches the version's metrics by name, label and description, then asks for one with the breakdown, filters and order it needs.
4. **MetricFlow compiles the SQL.** Upsolve does not reinterpret your metric. The compiled SQL then runs like any other agent query, so [row-level security](https://docs.upsolve.ai/ai-agent-builder/data-governance.md) and the data model's column list still apply.

If MetricFlow refuses a query — a group-by name that doesn't exist, say — the agent is told the closest valid names and corrects itself.

## Write metrics the agent can find

The agent finds a metric by its words, so the same habits that make a metric readable for people make it findable:

```yaml theme={null}
metrics:
  - name: spend
    label: Spend
    description: >
      PO value excluding cancelled POs: every Draft,
      Approved or Received PO counts.
    type: simple
    type_params: {measure: spend}

  - name: average_order_value
    label: Average order value
    description: Spend divided by active purchase orders.
    type: ratio
    type_params:
      numerator: spend
      denominator: active_po_count
```

* **`label`** — the name people use. The agent matches it first.
* **`description`** — what is in and out of the number, and the default period when none is asked for. This is the context that stops "active suppliers" being read as a status flag.
* **Dimensions** on the semantic models — everything you want to slice by. What a metric can be grouped by comes from MetricFlow, and the Metrics page shows the count for each metric.

## The Metrics page

In a connected workspace, **Repository → Metrics** lists the metrics of the **production** version: what the agent answers from right now. Each shows its type, how many names it can be grouped by, and its definition as MetricFlow parsed it. The page is read-only; change a metric in the repository and merge.

![Repository, Metrics tab: a list of MetricFlow metrics with their type and how many names each groups by, and the selected Spend metric's description and parsed definition](https://mintcdn.com/upsolve/ly_6q_O7-mhPeQj9/images/ai-agent-builder/content-layer/repository-metrics.png?fit=max\&auto=format\&n=ly_6q_O7-mhPeQj9\&q=85\&s=d3a3c1f12794513ef2ae420f08d4d9f6)

With **Promote each merge to production** off, a merge publishes a version nobody uses yet, so the page keeps showing production's metrics and says that a newer synced version exists.

## Alongside metrics written in Upsolve

Metrics become owned by the repository once a sync finds MetricFlow metrics in it. Until then, the workspace's Metrics page works as it does in any workspace.

If a dbt metric and a metric written in Upsolve have the same name (`gross_margin` and `gross-margin` are the same name), the dbt metric wins: the repository is the workspace's source of truth.

## Limits

* The [Builder Agent](https://docs.upsolve.ai/ai-agent-builder/builder-agent.md) can't propose metric changes. Edit the MetricFlow YAML yourself.
* Only metrics the dbt Semantic Layer defines are read. Metrics computed elsewhere (a BI tool, a dbt model that is just a table of numbers) are tables like any other.
* MetricFlow compiles metrics for **Postgres** (and Supabase and Timescale connections), **Redshift**, **Snowflake**, **BigQuery**, **Trino** and **Athena**. A workspace on ClickHouse, SQL Server or Microsoft Fabric still syncs its dbt models, prompts, skills and knowledge base, but the agent cannot answer from its MetricFlow metrics.
* When users must only see their own tenant's rows, declare row-level security in [`upsolve.yml`](https://docs.upsolve.ai/ai-agent-builder/content-layer/repository-reference#rls): the sync then refuses any model behind a measure that nothing filters. Add `require_on_facts` to insist that each has a condition of its own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.