Governed Metrics

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

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