Semantic Layer API Reference
The Semantic Layer API provides endpoints for managing semantic models, executing metric queries, natural language translation, query optimization, advanced metric computations, metric versioning, and model relationships. This page consolidates all endpoint references across the Semantic Layer services.
Authentication
All requests require a valid JWT token in the Authorization header and a tenant context via the X-Tenant-ID header. Some endpoints also accept an X-User-ID header for tracking authorship.
MDL Definition Endpoints
Base path: /api/v1/mdl
| Method | Path | Description |
|---|---|---|
GET | /api/v1/mdl | List all MDL definitions (paginated) |
GET | /api/v1/mdl/:mdlId | Get MDL definition by ID |
GET | /api/v1/mdl/by-name/:name | Get latest MDL definition by name |
GET | /api/v1/mdl/by-name/:name/versions | Get all versions of an MDL definition |
POST | /api/v1/mdl | Create a new MDL definition |
PUT | /api/v1/mdl/:mdlId | Update an MDL definition |
POST | /api/v1/mdl/:mdlId/validate | Validate an MDL definition |
POST | /api/v1/mdl/:mdlId/publish | Publish an MDL definition |
DELETE | /api/v1/mdl/:mdlId | Delete an MDL definition |
Natural Language Endpoints
Base path: /api/v1/nl
| Method | Path | Description |
|---|---|---|
POST | /api/v1/nl/translate | Translate question to semantic query |
POST | /api/v1/nl/ask | Translate and execute a question |
GET | /api/v1/nl/suggestions | Get query suggestions |
POST | /api/v1/nl/explain | Explain a semantic query |
POST | /api/v1/nl/validate | Validate a natural language question |
Translate Request Body
| Field | Type | Required | Description |
|---|---|---|---|
modelId | UUID | Yes | Semantic model ID |
question | String | Yes | Natural language question |
Ask Request Body
| Field | Type | Required | Description |
|---|---|---|---|
modelId | UUID | Yes | Semantic model ID |
question | String | Yes | Natural language question |
Suggestions Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
modelId | UUID | Yes | Semantic model ID |
query | String | No | Partial input text |
Advanced Metric Endpoints
Base path: /api/v1/metrics/advanced
| Method | Path | Description |
|---|---|---|
POST | /api/v1/metrics/advanced/cumulative | Compute cumulative metric |
POST | /api/v1/metrics/advanced/period-comparison | Period-over-period comparison |
GET | /api/v1/metrics/advanced/moving-average | Build moving average SQL |
POST | /api/v1/metrics/advanced/percentile | Build percentile SQL |
GET | /api/v1/metrics/advanced/ratio | Build ratio SQL |
GET | /api/v1/metrics/advanced/cagr | Build CAGR SQL |
GET | /api/v1/metrics/advanced/contribution | Build contribution SQL |
Common Advanced Metric Parameters
| Parameter | Type | Description |
|---|---|---|
modelId | UUID | Semantic model ID |
metricName | String | Name of the metric to compute |
timeDimension | String | Time dimension for temporal analysis |
startDate | LocalDate | Start of date range |
endDate | LocalDate | End of date range |
timeGrain | String | Temporal granularity |
groupByDimensions | List | Dimensions for grouping |
Metric Versioning Endpoints
Base path: /api/v1/metrics/versions
| Method | Path | Description |
|---|---|---|
GET | /api/v1/metrics/versions/:metricId/history | Get version history |
GET | /api/v1/metrics/versions/:metricId/versions/:version | Get specific version |
GET | /api/v1/metrics/versions/:metricId/current | Get current version number |
GET | /api/v1/metrics/versions/:metricId/compare | Compare two versions |
POST | /api/v1/metrics/versions/:metricId/rollback | Rollback to a version |
Compare Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fromVersion | Integer | Yes | Earlier version number |
toVersion | Integer | Yes | Later version number |
Rollback Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
targetVersion | Integer | Yes | Version to restore |
Relationship Endpoints
Base path: /api/v1/relationships
| Method | Path | Description |
|---|---|---|
GET | /api/v1/relationships | List all relationships |
GET | /api/v1/relationships/:relationshipId | Get relationship by ID |
GET | /api/v1/relationships/by-model/:modelId | Get relationships for a model |
POST | /api/v1/relationships | Create a relationship |
PUT | /api/v1/relationships/:relationshipId | Update a relationship |
DELETE | /api/v1/relationships/:relationshipId | Delete a relationship |
Create/Update Relationship Body
| Field | Type | Required | Description |
|---|---|---|---|
name | String | Yes | Relationship name |
sourceModelId | UUID | Yes | Source model ID |
targetModelId | UUID | Yes | Target model ID |
relationshipType | Enum | Yes | ONE_TO_ONE, ONE_TO_MANY, MANY_TO_ONE, MANY_TO_MANY |
joinType | Enum | Yes | INNER, LEFT, RIGHT, FULL, CROSS |
sourceKey | String | Yes | Source join column |
targetKey | String | Yes | Target join column |
condition | String | No | Additional join condition |
description | String | No | Description |
Query Optimization Endpoints
Base path: /v1/optimization
| Method | Path | Description |
|---|---|---|
POST | /v1/optimization/optimize | Optimize metric query |
POST | /v1/optimization/optimize-sql | Optimize raw SQL |
POST | /v1/optimization/analyze | Analyze query |
POST | /v1/optimization/compare | Compare query plans |
POST | /v1/optimization/rewrite | Rewrite SQL |
GET | /v1/optimization/rewrite-rules | List rewrite rules |
GET | /v1/optimization/cache/stats | Cache statistics |
GET | /v1/optimization/cache/patterns | Frequent query patterns |
DELETE | /v1/optimization/cache/:modelId | Invalidate model cache |
POST | /v1/optimization/cache/warm-up | Warm up cache |
POST | /v1/optimization/statistics/:modelId/refresh | Refresh statistics |
GET | /v1/optimization/statistics/:modelId | Get table statistics |
POST | /v1/optimization/statistics/:modelId/analyze | Analyze table |
GET | /v1/optimization/hints/:modelId | Get optimization hints |
Common Response Codes
| Code | Description |
|---|---|
200 | Successful operation |
201 | Resource created successfully |
204 | Successful deletion (no content) |
400 | Invalid request parameters |
401 | Authentication required |
403 | Insufficient permissions |
404 | Resource not found |
500 | Internal server error |