Metrics & Dimensions

💼 Business Context

• Gives business users a finite, trustworthy list of approved metrics instead of an intimidating list of every raw table and column
• Reduces the support burden on Analytics Engineering by making metric discovery self-service
• Owned by Analytics Engineering, curated with input from each business domain

🔌 Technical Overview

Every metric and dimension registered in the Semantic Layer is exposed through a catalog endpoint on the Analytics/AI API (a Docker container on Azure Container Apps), including its business description pulled from the Data Dictionary, valid dimension values, and which teams own it. New metrics go through a lightweight review process before appearing in the catalog, keeping the browsable list curated rather than growing unbounded with every ad hoc calculation anyone has ever written.

💾 Metrics Catalog Entry

GET /v1/metrics

[{
  "name": "net_revenue",
  "description": "Order total less refunds, in USD",
  "dimensions": ["region", "channel", "product_category"],
  "owner_team": "finance-analytics",
  "status": "approved"
}]

🔗 Integration Points

• Semantic Layer — the metric definitions this catalog exposes
• Data Dictionary (Metadata Layer) — supplies business-readable descriptions
• BI tools — query the catalog to populate metric picker UIs
• AI Copilot — uses the catalog to ground natural-language questions in valid, approved metrics

🧰 Services Consumed

• Owning microservice — Cxos.Intelligence.Api (see the Full Application Service Map)
• Database — Azure Database for PostgreSQL (semantic layer) + Azure Cache for Redis (query cache)

⚠️ Non-Functional Considerations

• Scale: catalog size tracks metric count (dozens to low hundreds), trivial relative to data volume
• Latency: catalog reads are cached aggressively since the list changes infrequently relative to query traffic
• Reliability: a metric review/approval step prevents unvetted calculations from appearing as if they were an official number
• Security/Privacy: catalog entries are metadata only; actual metric values still respect Access Control at query time

🎯 Enterprise Example

A new marketing analyst opens the BI tool's metric picker and finds net_revenue, churn_rate, and ltv_band already defined with descriptions and valid dimensions — building their first dashboard in an afternoon instead of a week of asking data engineering what tables to join.