The KPI workbench

A KPI is only as trustworthy as the answer to “where does this number come from?”. The KPI workbench is the set of kiri kpi verbs plus the KPI declarations in your contracts and reporting goals that make that answer mechanical: from the metric on the dashboard, back through the contract, down to the physical table on Databricks — with the owner, freshness, and definition attached at every step.

Where KPIs are declared

KPIs aren’t a separate registry you maintain by hand. They live in two places you’re already authoring:

Fact-contract measures. A measure on a gold fact contract — with its aggregation and definition — is a KPI. This is the canonical home for metrics that are properties of a materialised fact table.
ReportingGoal KPI specs. When you draft a ReportingGoal from a business question with kiri design, its spec carries the KPIs the goal is meant to answer. This is the goal-first home: the KPI exists because a business question demanded it, before any table exists.

Because both are discoverable, kiri kpi resolves a name against fact measures first, then against ReportingGoal specs — so a KPI is findable whether it’s already materialised or still just a declared intent.

`kiri kpi list`

List every KPI name discoverable in the project:

kiri kpi list

This is the inventory: every measure and every ReportingGoal KPI spec, by name. It’s the starting point for “what do we even claim to measure?” — useful when reconciling a dashboard’s tiles against what’s actually declared.

`kiri kpi describe`

Describe one KPI — its lineage, owner, freshness, and definition:

kiri kpi describe revenue
kiri kpi describe revenue --format json
kiri kpi describe customer_churn --no-freshness

kiri kpi describe NAME composes the full exec-facing record for a KPI:

Definition — what the KPI is and how it’s computed.
Owner and domain — who’s accountable and which business domain it belongs to.
Classification and SLA — the sensitivity and the freshness/SLA bar the underlying data is held to.
Lineage — the path from the KPI down to its physical source.
Freshness — the live freshness signal, read from the build manifest.

Flags:

--target picks the environment whose manifest is read for the freshness lookup.
--no-freshness skips the manifest read entirely — faster, and freshness comes back as unknown. Use it when you only need lineage and ownership.
--format text|json — text for a human, json to feed a dashboard’s data-lineage panel or a governance report.

Goal-to-data traceability

The workbench’s whole point is an unbroken chain from the business question to the bytes on Databricks:

ReportingGoal → Contract → Table.

ReportingGoal. A business question, captured with kiri design, naming the facts, dimensions, and KPIs that would answer it. This is the why: the KPI exists because someone needed to know something.
Contract. The gold fact and dimension contracts that satisfy the goal. The KPI’s measure lives here, alongside its classification, owner, and SLA. This is the what: the governed definition.
Table. The physical gold table your dbt build materialised into the Databricks SQL warehouse. This is the where: the actual data the number is computed over.

kiri kpi describe walks this chain in reverse when you ask about a number, so “where does revenue come from?” returns the contract that defines it, the goal that motivated it, the table it’s computed over, the owner to ask, and how fresh it is — not a shrug.

How KPIs get drafted alongside the models

You don’t declare KPIs in isolation from the models that serve them. The goal-first flow ties them together:

# 1. Capture the business question as a ReportingGoal (KPIs live in its spec)
kiri design --goal-file questions/revenue.md --write

# 2. Draft the gold fact that carries the KPI's measure
kiri suggest gold --goal revenue --fact orders --write

# 3. Inspect the KPI end-to-end once the models exist
kiri kpi describe revenue

Because the KPI is declared in the goal and materialised as a measure on the fact contract, its lineage and ownership are a byproduct of authoring the models — not a separate metadata chore you have to remember to keep in sync.

Using it in review

Two habits make the workbench pay off:

Reconcile before you ship a dashboard. Run kiri kpi list and check every tile on the dashboard maps to a declared KPI. A tile with no matching KPI is a number with no owner and no definition — the exact thing the workbench exists to eliminate.
Answer “is this current?” with --target prod. When an exec questions a figure, kiri kpi describe <name> --target prod gives the live freshness and the owner in one command — a defensible answer instead of a guess.

The KPI workbench doesn’t compute your metrics for you; your dbt models and the semantic layer do that. What it gives you is the governance around the number — the traceability, ownership, and freshness — so every KPI on a dashboard can be traced back to the question that asked for it and the table that answers it.