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

# get_metric

> Compiles and runs a pre-declared metric — the only execution path SchemaBrain ships.

<Note>
  **Layer:** Semantic layer
</Note>

Computes a pre-declared metric against the live database. Returns the
materialised rows, the parameterised SQL the compiler emitted, and a
`fingerprint` linking back to the immutable audit row. The agent never
writes SQL itself for declared metrics — SchemaBrain compiles and
parameter-binds.

```json theme={null}
{
  "rows": [
    {"group_col_0": "Enterprise", "active_subscriptions": 4},
    {"group_col_0": "Free", "active_subscriptions": 8},
    {"group_col_0": "Pro", "active_subscriptions": 2}
  ],
  "row_count": 3,
  "sql_skeleton": "SELECT \"plan\".\"title\" AS group_col_0, count(\"subscription\".\"id\") AS active_subscriptions FROM \"public\".\"subscriptions\" AS \"subscription\" JOIN \"public\".\"plans\" AS \"plan\" ON \"subscription\".\"plan_id\" = \"plan\".\"id\" GROUP BY group_col_0 ORDER BY group_col_0 ASC LIMIT :p_limit",
  "sql_params": {"p_limit": 1000},
  "fingerprint": "f3a1c89e...",
  "required_joins": ["subscription_plan"],
  "fan_out_join_names": [],
  "pii_categories": [],
  "token_estimate": 239
}
```

* `group_by` and `filters` use `entity.column` form (e.g. `plan.title`,
  `invoice.issued_at`) — never physical `schema.table.column`.
* `filters` is `(column, op, value)` with closed-set ops: `eq`, `ne`, `lt`,
  `lte`, `gt`, `gte`, `in`, `not_in`, `is_null`, `not_null`.
* Values bind as parameters — never inlined into SQL.
* `fan_out_join_names` flags joins where the cardinality could inflate
  rows. When the list is non-empty the envelope downgrades to
  `status="degraded"` with `confidence="MEDIUM"` — this is the
  machine-readable signal the agent should surface to the user, not the
  list itself.
* `pii_categories` propagates the MAX-sensitivity + UNION-categories of
  every column touched, and is what `--pii-block` filters against.

Use `list_entities` instead when you don't yet know what's defined.
`get_metric` only computes pre-declared metrics — it will never run
arbitrary SQL.