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

# Governed Metrics

> Browse, create, edit, and delete dbt-defined metrics from the Models → Metrics catalog.

Governed Metrics is a list-to-detail catalog in the **Models → Metrics** sub-tab. Operators
with the `create_proposals` capability can create, edit, and delete metrics directly from the
catalog. **Changes apply to both Staging and Production.**

## What a governed metric is

When the model-building agent generates a dbt project it also authors a dbt MetricFlow semantic
YAML that defines each business metric computationally. Every metric is materialized as a column
in its mart, so any BI tool pointed at the marts reads the same governed number. The Metrics
catalog exposes those definitions in the portal without requiring the operator to read YAML
directly.

## Metrics catalog

Access the catalog from **Models → Metrics**. The catalog loads from `GET /api/semantic/metrics`
(environment-scoped) and shows:

* A searchable list of all metrics defined for the active environment.
* A detail panel for the selected metric with:
  * **Label** and **Description** — human-readable name and purpose.
  * **Type** and **Measure/Aggregation** — the metric kind (e.g. `simple`) and its aggregation
    expression (e.g. `sum(wins)`).
  * **Mart** — the mart model the metric belongs to.
  * **Grain** — the time grain the metric is pre-aggregated to.
  * **Time dimension** — the time dimension used for grain alignment.
  * **Column** — the column name as materialized in the mart.
  * **Lineage handoff** — a link to trace the metric back through the Lineage sub-tab.
  * **Governance badge** — one of `verified`, `draft`, `deprecated`, or unset (cleared). Set
    by the operator; visible in the catalog.

## Source of truth

Metric definitions live in the customer's dbt project and git — Platinur never stores metric
definitions in its own database (only portal metadata). The semantic YAML is generated and
maintained by the model-building agent and preserved through human edits. The materialized mart
column and the catalog entry are always in sync because both derive from the same YAML file.

## Editing metrics

Operators with the `create_proposals` capability can **create, edit, and delete** metrics from
the catalog detail panel. Editing is available in both Staging and Prod views because changes
are committed directly to both git branches simultaneously — there is no separate PR or promotion
step for metric edits. The UI shows: **"Changes apply to both Staging and Production."**

### Prerequisites

Metric editing requires:

* **GitHub configured** — changes are made durable by committing directly to both the staging
  and production git branches. If GitHub is not configured, editing is disabled in the UI with
  the reason shown.
* **The bound warehouse is available** — definitions are validated by running the aggregation
  against the staging marts before anything is written.
* **`create_proposals` capability** — the same capability required for assistant interview and
  proposal routes.

### Editable fields

| Field           | Notes                                                                                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Label**       | Human-readable display name for the metric.                                                                                                                                                                  |
| **Description** | Free-text explanation of what the metric measures.                                                                                                                                                           |
| **Status**      | `verified`, `draft`, `deprecated`, or cleared (empty).                                                                                                                                                       |
| **Definition**  | The aggregation function (`sum` / `avg` / `min` / `max` / `count` / `count_distinct`) applied to a SQL **expression** built from existing columns of the metric's mart (e.g. `wins`, or `wins - penalties`). |

`owner` is not an editable field and is not stored.

### Creating a metric

Use the **New metric** action in the catalog. Required fields: the mart the metric belongs to,
an aggregation function, and a SQL expression over that mart's existing columns. The definition
is validated against the staging marts in the bound warehouse before anything is written. On success the
metric is added to the semantic YAML in both the staging and prod workspaces and committed
directly to both git branches.

### Editing a metric

Open the metric in the detail panel and edit the fields above. When the definition changes
(aggregation or expression), it is validated by running the aggregation against the staging
marts in the bound warehouse first. On success the changes are applied to both workspaces and committed
directly to both git branches.

### Deleting a metric

The delete action checks whether other metrics or dashboard pages reference the metric and
returns a warning before confirming. Pass `confirm` to apply. On confirmation the metric and its
measure are removed from both environments.

### What happens if the expression references a missing column

If the SQL expression references a column that does not exist in the mart, validation fails and
nothing is written. The error tells the operator to add that column to the mart via the
Assistant first — metric editing works over existing mart columns; adding a new underlying
column is a mart/model change that goes through the normal assistant proposal flow.

## How edits survive agent rebuilds

When the model-building agent regenerates the semantic YAML (for example after an Initial Run
or a model rebuild), it preserves each metric's human-edited label, description, and
`meta.platinur` governance block for metrics that already exist. Human edits are not overwritten
by agent runs.

## API

| Method   | Route                          | Notes                                                                                                                                                                                                                                          |
| -------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`    | `/api/semantic/metrics`        | Returns enriched metric records for the active environment.                                                                                                                                                                                    |
| `POST`   | `/api/semantic/metrics`        | Create a governed metric. Body: `{name, label?, description?, mart, grain?, agg, expr, status?}`. Validates against the staging marts in the bound warehouse; commits to both git branches on success. Requires GitHub and `create_proposals`. |
| `POST`   | `/api/semantic/metrics/{name}` | Edit a governed metric. Body: `{label?, description?, status?, agg?, expr?}`. Definition changes are validated before commit. Requires GitHub and `create_proposals`.                                                                          |
| `DELETE` | `/api/semantic/metrics/{name}` | Delete a governed metric. Add `?confirm=true` to apply; without it, returns a 409 with reference warnings. Requires GitHub and `create_proposals`.                                                                                             |