Where Should Your Metric Definitions Live? (Repo vs Platform)

I’d choose one place to edit and approve metrics: a repository for code review and portability, or a platform for direct business ownership. If your team needs both, keep one edit path and publish approved definitions to the other.

The test isn’t where a definition sits. It’s whether your warehouse query, dashboard, and AI answer use the same formula, rules, and version. In the article’s example, all three should return $92,000.00 from the same test data.

Quick Comparison

Decision point	Repository-first	Platform-first
Ownership	Engineers implement; business owners approve	Analysts or business owners edit within permissions
Review	Pull requests and automated tests	Drafts, validation, and approval steps
Access	Publish docs for nontechnical users	Make formulas and filters visible
Portability	Keep inspectable files	Check complete exports and APIs
Audit trail	Track commits, approvals, and releases	Track edits, approvals, and publication
AI use	Publish approved logic and metadata	Expose approved definitions within permissions
Main risks	Review delays and unclear ownership	Hidden filters and competing definitions

Before publishing, I’d name the owners, test the calculation, and attach a version and effective date. In a hybrid setup - including GitHub-backed context in Querio - I’d keep drafts separate from trusted metrics and stop publication when copies disagree.

One edit path. One approved definition. The same rules everywhere.

::: @figure {Metric Governance: One Edit Path, Consistent Results} :::

Repository vs Platform: Who Owns and Reviews Metrics?

Dimension	Repository-first	Platform-first
Ownership	Data or analytics engineering implements metrics; business owners approve their meaning.	Analysts or business owners maintain definitions within assigned permissions.
Review workflow	Pull requests, required approvals, automated checks, and controlled releases.	Draft approval, validation, and controlled publishing.
Accessibility	Works well for technical contributors; nontechnical users may need documentation or a catalog.	Makes discovery and contribution easier when formulas and filters are visible.
Portability	Inspectable files support reuse, though warehouse-specific SQL may need edits.	Depends on complete exports, APIs, and reuse outside the platform.
Auditability	Commits, review discussions, test results, and deployment records.	Version history, editor identity, approval records, and publication timestamps.
AI access	Agents need deployed definitions and metadata - not just repository access.	Agents need permission-aware access to trusted definitions and metadata.
Failure risks	Review bottlenecks, unclear ownership, and overly technical definitions.	Hidden filters, duplicate definitions, and weak publishing boundaries.

Repository-First: Review and Portability

Git history is not governance. Use protected branches, required reviews, and passing status checks to block high-impact changes until the right people sign off. Keep implementation, tests, and release metadata together. Then link the approved release to the deployed definition.

The trade-off? Contributing takes more effort. A finance owner may need to approve an exclusion without knowing SQL or YAML. Separate business approval from implementation, and publish searchable documentation so nontechnical users can find the right definition.

Commits preserve logic, not results. To reproduce an earlier number, you also need the matching source-data version. A metric like net revenue makes that distinction easier to see.

Platform-First: Access and Publishing Controls

Platform ownership suits analyst-led maintenance and frequent business input - as long as editing and publishing have separate permissions. Require visible formulas, lineage, and version history. Check that exports preserve the full definition, not just its name or displayed result. Strict review and portability are possible, but the controls must work in practice.

Inspect the complete calculation path. Dashboard filters can change a trusted metric’s result. Duplicate workspace definitions can also produce competing numbers. Use an AI semantic layer as your approved metric catalog, link dashboard tiles to their definitions, and keep drafts out of default dashboards and AI metric discovery. Viewers should be able to inspect definitions within their permissions.

These governance rules apply whether a metric powers a dashboard or an AI answer.

Choose Ownership for Shared and Draft Metrics

Favor repository ownership for financial, regulated, or cross-department metrics when testing and portability take priority. Choose platform ownership when business contribution matters more and publishing controls can be enforced.

Use draft → reviewed → trusted → deprecated, with named authority for promoting metrics, version tracking, and replacement guidance. When ownership changes, record the final version, new owner, approval rules, and authoritative location. Make the old location read-only so it doesn’t become a second editing path.

Next, a net revenue example shows how a definition moves from edit to publish.

Net Revenue Example: Repository vs Platform

Set the Formula and Reporting Rules

A simple formula still needs one approved definition. Net revenue makes a useful test case: the policy is specific, but everyone reporting the metric needs the same source of truth.

For this hypothetical B2B SaaS company, net_revenue_usd is $100,000.00 − $5,000.00 − $2,000.00 − $1,000.00 = $92,000.00. Exclude taxes and pass-through fees, subtract refunds, credits, and finalized chargebacks, and document how to treat disputes and FX adjustments. This is a policy-defined operating metric, not GAAP revenue, cash collected, or net revenue retention. Finance approves which revenue sources qualify. Report in USD at a monthly grain, using calendar-month boundaries in America/New_York. Exclude test accounts, voids, and non-revenue cash entries. Subtract applied credits under the approved policy; record the FX source, FX date, and adjustment rule.[5][6][7]

Contract item	Repository-first	Platform-first
Formula	Store the net revenue formula in the repo.	Store it in the platform’s metric definition.
Exclusions	Store tested exclusions in the revenue model.	Store required filters in the metric or source model - not dashboard tiles.
Owners	Record the controller and analytics engineer in repo metadata.	Record the same owners in metric metadata.
Approvals	Capture finance and technical sign-off in the pull request.	Capture the same sign-offs in the metric’s approval record.
Effective date	Record version 2.0.0 and effective_from: 2026-10-01.	Publish the version and effective date; retain the previous definition.
Publication	Deploy the definition and metadata to dashboard and agent interfaces.	Expose the approved identifier to dashboards and supported agent consumers.
Test	Run the $92,000.00 fixture in CI.	Check the same fixture through validation queries.

With the formula set, teams need a clear path for reviewing and releasing changes.

Approve and Publish a Definition Change

For a change that excludes disputed payments starting October 1, 2026, define disputed as open, lost, or finalized before review begins. Repository-first uses a pull request; platform-first uses a draft and approval workflow. Finance approves the policy and whether earlier periods will be restated. The technical owner validates joins and deployment. Compare September and October 2026 on the same frozen snapshot, then report the old result, proposed result, variance, and affected invoices.

Test all dispute states plus refunds and chargebacks. Excluding a payment from gross revenue must not also subtract its chargeback. Use stable adjustment IDs linked to the original charge, deduplicate repeated events, and define precedence for overlapping refunds, credits, and chargebacks. Retain the prior definition and reconcile the first October result against processor and general-ledger totals. Publish the same approved net revenue version for dashboards and AI answers.[6]

Use the Same Metric in Dashboards and AI Answers

Dashboards and agents should resolve net_revenue_usd to one approved version, query live warehouse data, and show the definition metadata with the result.[8][4]

Separate draft and trusted versions can break that consistency if teams don't set sync rules. For teams that need one edit path while keeping trusted and experimental metrics separate, the next question is how a hybrid setup would work.

Hybrid Setup: Keep Definitions in Sync

A hybrid setup pairs repository review with platform-based discovery and self-service. It also adds publishing and sync work. Make the repository the only edit path when engineering owns changes, and the platform the only edit path when business users own them. Governance then depends on keeping definitions in sync - not just controlling edits.

Use One Edit Path and Show the Version

Keep a stable metric ID. Publish each definition with its approved version, effective date, and release ID. Update the definition and docs in the same change set, then validate before release.

The latest edit should never win automatically. When definitions conflict, stop publication, mark the platform copy as stale, and send the change through the authoritative review process. Keep the last approved version active for the periods it covers, but block unverified copies from new analysis.

This rule matters even more when trusted metrics and drafts sit side by side.

Keep Trusted Metrics Separate From Experiments

Give experiments separate names and IDs. Keep them out of production dashboards and agent context.

After publication, check saved queries, dashboard filters, and agent context for stale references. Matching names alone aren't enough. Retain deprecated definitions so users can interpret historical results, but remove them from selections for new analysis.

For a governed context layer to work, users and agents need to see these boundaries clearly.

How Querio Connects Governed Context to Self-Service

Querio stores governed SQL, Markdown, and Python context in GitHub. Humans approve agent-proposed updates. This shared context powers live warehouse queries and governed self-service without CSV exports, helping dashboards and AI answers use consistent definitions.

Sync does not enforce correctness: teams still need tests, permissions, and query review to verify joins, exclusions, and date handling.

Conclusion: Choose Where Metrics Live, Then Publish Them

Choose based on who owns the metrics and how they’re published - not just where they’re stored. Use a repository for strict review and portability. Use a platform when business owners need to edit and publish directly.

Before release, name the business and technical owners, choose one edit path, and test net revenue. Then publish the approved version and its effective date.

Before production, run the warehouse query, check the dashboard, and ask the AI agent the same question:

“What was net revenue in the United States in September 2026?”

Compare the formula, exclusions, filters, time zone, currency, and version across all three. Ship only when all three match the approved definition.

FAQs

::: faq

How do we migrate metrics without breaking dashboards?

Treat metric definitions like version-controlled code. Before updating dashboards, centralize the logic in a governed semantic layer, dbt model, or warehouse view. Review changes through Git pull requests, and use automated tests to catch issues.

Map each existing dashboard calculation to the centralized definition. Match the formulas, time windows, and exclusions, then compare old and new results in staging. Roll out production updates in phases so dashboards and AI agents use the same source of truth. :::

::: faq

When should a metric change trigger historical restatements?

A metric change should trigger historical restatements when it changes what past periods mean - not just how new data is labeled. Changes to grain, filters, exclusions, or time windows require restatement. That includes changes to what counts as net revenue, so past dashboards and AI answers don’t reflect outdated rules.

Version metric logic and downstream certified outputs so teams can explain updates and apply them consistently. Querio’s governed semantic layer supports consistent metric definitions that teams can inspect. :::

::: faq

How can we detect metric drift in AI answers?

Require AI to use a governed semantic/context layer as the single source of truth. It should reuse certified metric logic - joins, filters, and exclusions - from versioned SQL/dbt and stay in sync with live warehouse metadata, not stale copies [1][2].

Validate answers with SQL/Python that people can inspect and edit. Use lineage to trace which metrics, reports, and agents are affected when upstream schemas or definitions change [1][3]. :::