Shared Semantic Layer — Solution Overview
Context
Every feature built on top of analytical data — dashboards (via shared runtimes), reports, filters, and AI capabilities — currently interprets data independently. Each feature decides for itself what a column means, how to search it, and which date column is canonical.
The shared semantic layer replaces per-feature interpretation with a single, compiled business model that every feature consumes.
Core Architectural Principles
Component Map
| Component | Responsibility | Analogy |
|---|
| Semantic Registry | Holds concepts, physical mappings, identity, hierarchy, and capability bounds. | Dictionary of concepts |
| Relationship Registry | Holds table relationships, foreign keys, cardinality, and chasm-trap guards. | Map of table joins |
| Entity Registry | Holds real-world value aliases and phonetic fuzzy-match indices. | Real-world lookup table |
| Statistics Registry | Holds live profile metrics (min/max, null rates, top values). | Health snapshot |
| Compiler | Reads four registries; emits read-only, pre-computed projection views. | Cheat-sheet compiler |
Why Four Registries, Not One?
| Registry | Rate of Change | Validation Mechanism | Isolation Risk |
|---|
| Semantic Registry | Rarely (Schema changes) | CI-gated PR review | Routine alias fixes shouldn't trigger business model reviews. |
| Relationship Registry | Rarely (Migrations) | CI-gated PR review | Join changes isolated from value mapping. |
| Entity Registry | Continuously (New vendors/typos) | Lighter, semi-automated | Prevents heavy review on routine value additions. |
| Statistics Registry | Automated refresh cadence | Automated freshness checks | Statistics updates won't trigger model re-validation. |
The Compiler & Projection Views
The compiler takes raw registries as input and outputs four purpose-built projection views:
Execution Runtime & Session Isolation
```typescript filename="query-resolution-pipeline.ts"
// High-level query planning pipeline
interface ExecutionPipeline {
sessionId: string; // Isolated per user session
userQuery: string;
// Step 1: Disambiguate concepts using Prompt View
resolveConcepts(query: string): Promise<SemanticConcept[]>;
// Step 2: Build deterministic SQL via Planner View
buildExecutableQuery(concepts: SemanticConcept[]): Promise<ExecutableQuery>;
}
```
Responsibilities Summary
• Semantic Registry: Concept definitions & capabilities.
• Relationship Registry: Joins, cardinality, fact/dimension roles.
• Entity Registry: Real-world name/value matching.
• Statistics Registry: Live profile metrics.
• Compiler: Emits purpose-built read-only views.
• Query Planner: Resolves chart subscriptions & AI tool calls to SQL.