Metric Versioning, Deprecation, Tests, Documentation, and Preventing Dashboard-Specific Business Logic

Learning outcomes

1. Metric changes are API changes for data consumers

Once dashboards, finance extracts, notebooks, alerts, and applications depend on gross_revenue_usd.v1, its semantics are an interface. Changing paid-status treatment, currency conversion, date timezone, or return handling can change historical results even if the metric name stays the same. Therefore a semantic change is versioned and reviewed like a contract change.

The lab keeps an intentionally ambiguous revenue_legacy.v0 entry as deprecated evidence and points consumers to gross_revenue_usd.v1. It does not overwrite the legacy record and pretend the old dashboard always meant the new definition.

2. Registry state is observable

active_customers.v1   | v1 | active     | growth-analytics  | replacement=NULLgross_revenue_usd.v1  | v1 | active     | finance-analytics | replacement=NULLperiod_retention.v1    | v1 | active     | growth-analytics  | replacement=NULLrevenue_legacy.v0      | v0 | deprecated | legacy-bi         | replacement=gross_revenue_usd.v1

Each active specification is serialized canonically and hashed. A hash is not a proof that the definition is correct; it is an identity for the exact reviewed bytes. When the specification changes, the hash changes, which forces compatibility tests for accelerators, adapters, golden results, and consumers.

3. Controlled failure: changing v1 in place

Safer options depend on intent: create a separately named net_revenue_usd.v1 if it is a different business concept, or create gross_revenue_usd.v2 if the same named contract has an intentionally breaking definition. Keep v1 during a migration window, publish differences, identify consumers, and set a deprecation date.

4. Tests belong to the metric contract

5. Documentation is executable context, not a prose afterthought

A useful metric page records name/version, business question, source event, fact grain, formula, filters, dimensions, time semantics, currency/units, security inheritance, owner/steward, freshness/SLO, lineage, examples, known exclusions, golden tests, version history, deprecation status, and consumer migration notes. Generated SQL can be shown as evidence but should not replace the business definition.

Documentation must distinguish what the metric means from how the current engine computes it. That separation lets AtlasMart change from SQLite teaching harness to a cloud warehouse without silently changing semantics.

6. Consumer migration and deprecation

1. Register the new version/metric with owner approval.
2. Run historical and edge-case comparisons against the old definition.
3. Enumerate downstream consumers using lineage/query telemetry.
4. Publish a migration window and changed-result examples.
5. Dual-run critical reports; require sign-off.
6. Mark old version deprecated but still reproducible.
7. Disable only after consumers migrate and rollback criteria are satisfied.

Urgent correctness/security fixes may require faster action, but the audit record should still preserve who approved the change and what historical outputs are affected.

7. Prevent dashboard-specific business logic

Dashboards may select dimensions, filters explicitly allowed by the contract, and visual calculations such as percentages of displayed total when clearly labeled. Core definitions such as “paid,” active-customer identity, retention denominator, currency conversion, or security must not be reimplemented independently in each workbook. CI can search semantic models/dashboard metadata for forbidden duplicate expressions where the tooling exposes them.

8. Production judgment and bridge

Versioning increases governance overhead, so use it for decision-relevant semantics rather than cosmetic changes. A formatting change from $820.00 to $820 need not create a new business metric version; changing the population or denominator does.

Lesson 5 combines the registry, compiler, golden tests, RLS, currency gate, acceleration cross-check, and lineage into one reproducible acceptance workflow.

Knowledge check

Authoritative references

• Kimball Group — Conformed DimensionsBackground for shared dimensional meaning across analytical consumers and processes.
• Kimball Group — Fact TablesGrain-first fact-table guidance underlying safe metric aggregation.
• dbt — MetricFlow overviewCurrent official example of a semantic metric engine. It is a non-prerequisite product reference, not the course's semantic source of truth.
• dbt — Semantic LayerCurrent official example of centrally defined metrics consumed across tools; exact capabilities and syntax are product-specific.
• PostgreSQL — Row Security PoliciesOfficial engine-specific reference for row-level security. The mandatory local lab simulates entitlement filtering with joins instead of claiming SQLite has equivalent native RLS.
• SQLite — SELECTOfficial semantics for the deterministic local SQL examples.
• Python — sqlite3Standard-library interface used by the no-cost local lab.

9. Lab cleanup/reset

The mandatory examples use only the deterministic local Chapter 20 fixture. Delete atlasmart_ch20_lab (or your configured local output directory) and rerun python ch20_lab.py to recreate a clean state. The script recreates the SQLite database and metric/report files; it does not create cloud resources or modify the academy repository.