Semantic Metrics Layer

A governed metrics system that gives Finance, Sales, and Product consistent answers from one dimensional model. Metric definitions, dimensions, access policies, and SQL generation are version-controlled and tested.

The project runs with Python and SQLite, but its design maps to Snowflake plus dbt Semantic Layer, MetricFlow, Cube, LookML, or a custom metrics API.

Why this matters

When every dashboard defines ARR or active customers independently, teams can produce individually reasonable but mutually inconsistent numbers. A semantic layer centralizes calculation logic, join paths, grain, descriptions, and access rules so BI tools consume metrics rather than recreate them.

Capabilities

• SCD Type 2 customer dimension with point-in-time attribution
• Monthly subscription fact at customer grain
• Versioned metric and dimension contracts
• Safe SQL compilation from requested metrics and dimensions
• Role-based metric access for Finance, Sales, and Product
• Consistency, SCD overlap, and metric reconciliation tests
• Example metric queries and JSON outputs

Run

make all

Query the semantic layer:

python3 src/query_metrics.py --role finance --metrics arr acv nrr --dimensions month_start segment
python3 src/query_metrics.py --role product --metrics active_customers ai_adoption_rate --dimensions month_start

Invalid dimensions, unknown metrics, and unauthorized requests fail closed.

Architecture

Raw customers + subscription snapshots
                 │
                 ▼
       dim_customer_scd2 ─────┐
                              ├──► semantic compiler ──► governed SQL
       fct_subscription_monthly┘            ▲
                                            │
                              metric + access contracts
                                            │
                         Tableau · Sigma · notebooks · API

See docs/governance.md and docs/lineage.md.