Semantic Layer Architecture
The Semantic Layer provides a unified abstraction over physical data sources, allowing users to query business metrics and dimensions using semantic concepts rather than raw SQL. Built on Model Definition Language (MDL) and integrated with WrenAI for natural language support, the Semantic Layer translates business questions into optimized SQL queries against the underlying data platform.
Architecture Overview
Natural Language / Metric Query
|
v
Semantic Layer API
|
+-----------+----------+-----------+
| | | |
MDL Service NL Engine Query Metric
(Models) (WrenAI) Optimizer Versioning
| | | |
+-----------+----------+-----------+
|
v
SQL Compilation
|
v
Query Engine (Trino)Core Components
| Component | Description |
|---|---|
| MDL Service | Manages Model Definition Language definitions for semantic models |
| Semantic Model Service | CRUD operations for semantic models, metrics, and dimensions |
| Metric Query Service | Compiles and executes metric queries against models |
| Natural Language Engine | Translates natural language questions to semantic queries via WrenAI |
| Query Optimizer | Optimizes compiled SQL using cost-based analysis and rewrite rules |
| Metric Versioning | Tracks metric definition changes with rollback capability |
| Relationship Service | Manages joins and relationships between semantic models |
Key Concepts
| Concept | Description |
|---|---|
| Semantic Model | A logical representation of a data entity with metrics and dimensions |
| Metric | An aggregatable measure defined on a model (SUM, COUNT, AVERAGE, etc.) |
| Dimension | A categorical or temporal attribute used for grouping and filtering |
| Relationship | A join definition between two semantic models |
| MDL Definition | A declarative specification of models, metrics, dimensions, and relationships |
| Time Grain | The temporal granularity for time-based analysis (DAY, WEEK, MONTH, QUARTER, YEAR) |
Data Flow
| Step | Description |
|---|---|
| 1 | User submits a metric query or natural language question |
| 2 | The Semantic Layer resolves models, metrics, and dimensions |
| 3 | Relationships are traversed to build JOIN clauses |
| 4 | The query compiler generates SQL from the semantic query |
| 5 | The query optimizer applies rewrite rules and cost-based optimization |
| 6 | The optimized SQL is sent to the Query Engine for execution |
| 7 | Results are returned with column metadata |
Tenant Isolation
All semantic layer operations are scoped to a tenant via the X-Tenant-ID header. Each tenant has its own set of models, metrics, dimensions, and relationships. Cross-tenant data access is not permitted.
Section Pages
| Page | Description |
|---|---|
| Semantic Models | Model creation, configuration, and lifecycle |
| Metric Queries | Compiling and executing metric queries |
| Natural Language | Natural language to query translation |
| Query Optimization | SQL optimization and plan caching |
| Advanced Metrics | Cumulative, period-over-period, and statistical metrics |
| Metric Versioning | Version history and rollback for metrics |
| Relationships | Model relationships and join definitions |
| API Reference | Complete endpoint reference |