Skip to main content
Governed metrics turn business language into reusable, version-controlled calculations. The Models → Metrics tab is a searchable, read-only catalog for the active environment; create or change a metric by asking the Assistant in Staging.

​
What is governed

A useful metric definition records more than a label:
  • a stable name and plain-language description;
  • the serving mart/model it belongs to;
  • the measure or expression and aggregation;
  • its reporting grain and time dimension where relevant;
  • dimensions that can safely break it down;
  • tests and model lineage that make the input trustworthy;
  • an optional governance state such as verified, draft, or deprecated.
Definitions live with the customer’s dbt project in GitHub. The catalog reads those definitions and model metadata; it is not an unrelated copy in the portal database.

​
Browse the catalog

Switch to the environment you care about and open Models → Metrics. Search by name or description, then open a metric to inspect its calculation, mart, grain, dimensions, and lineage. If the active environment has no definitions, the page shows No governed metrics yet. Staging and Production can differ while a metric proposal is unreleased. Production always shows the definitions on the configured production branch/runtime.

​
Create or update metrics

Ask the Assistant in Staging, for example:
  • “Define governed metrics for weekly active players, completed matches, and win rate.”
  • “Add a verified player connection-rate metric broken down by platform.”
  • “Change completed matches to exclude abandoned sessions and explain the impact.”
The Assistant first inspects the existing marts and contracts. It should prefer calculations the current serving layer can support, add a model only when the required grain is genuinely missing, and avoid inventing a metric from unavailable columns. Before committing, Platinur validates the current dbt project—including semantic parsing, model dependencies, mart tests, and the relevant aggregation against the Staging warehouse. A passing change appears in Promotions with its files, diff, and dependencies. Release it through the same dependency-aware plan as any model or dashboard change.

​
MetricFlow and time-spine constraints

Some semantic metrics require a valid MetricFlow time spine at day granularity or smaller. The Assistant must inspect the installed dbt/MetricFlow contract and existing project before writing semantic YAML. It should create one valid time-spine model only when required, reference existing metric names exactly, and validate parsing before retrying a warehouse run. Repeatedly editing YAML around the same parse error is not acceptable completion. If the project or installed adapter cannot support the requested semantic definition safely, the run stops without committing and explains the concrete blocker.

​
Modeling guidance

  • A metric must answer a business question, not merely expose every numeric mart column.
  • Ratios define numerator, denominator, null/zero behavior, and aggregation semantics explicitly.
  • Grain must match the mart or be derived without double aggregation.
  • Time-based metrics name the canonical time dimension.
  • Descriptions state inclusions/exclusions so the same number is interpreted consistently.
  • Dashboard KPI cards should consume governed relations/definitions and remain valid when a query returns zero rows.
The generated dbt/semantic files and Git history remain the source of truth. Promotions is the place to review and Undo a staged metric change; the Metrics catalog is for understanding the current environment.
The generated API reference still includes legacy session-authenticated create/edit/delete metric routes for compatibility with older clients. They write directly to both branches and do not follow the current release contract. The portal does not use them; do not build new integrations on those routes.