Semantic Models

Semantic Models are the foundation of the Semantic Layer. Each model represents a logical data entity backed by a physical table or view, and defines the metrics (measures) and dimensions (attributes) available for querying. Models are managed through the MDL (Model Definition Language) service and follow a lifecycle from draft to published.

Model Structure

A semantic model contains the following components.

Component	Description
Name	Unique identifier within the tenant
Table reference	Physical table or view backing the model
Metrics	Aggregatable measures (revenue, count, average)
Dimensions	Categorical or temporal grouping attributes
Relationships	Joins to other models
Data source	Connection to the underlying data platform

Model Status Lifecycle

Status	Description
`DRAFT`	Model is being authored and is not available for queries
`PUBLISHED`	Model is validated and available for metric queries
`DEPRECATED`	Model is being phased out and will be removed

MDL Definition

Models are defined using MDL (Model Definition Language) declarations. Each MDL definition specifies models, metrics, dimensions, and their configurations.

{
  "name": "sales_analytics",
  "description": "Sales data model for analytics",
  "models": [
    {
      "name": "orders",
      "tableName": "delta.sales.orders",
      "metrics": [
        {
          "name": "total_revenue",
          "type": "SUM",
          "expression": "order_total",
          "description": "Sum of all order totals"
        },
        {
          "name": "order_count",
          "type": "COUNT",
          "expression": "*",
          "description": "Total number of orders"
        }
      ],
      "dimensions": [
        {
          "name": "order_date",
          "type": "TIMESTAMP",
          "expression": "created_at",
          "isTimeDimension": true
        },
        {
          "name": "region",
          "type": "STRING",
          "expression": "shipping_region"
        }
      ]
    }
  ]
}

Metric Types

Type	Description
`SUM`	Sum of values
`COUNT`	Count of rows
`COUNT_DISTINCT`	Count of distinct values
`AVERAGE`	Mean of values
`MIN`	Minimum value
`MAX`	Maximum value
`MEDIAN`	50th percentile
`PERCENTILE`	Arbitrary percentile
`DERIVED`	Computed from other metrics (formula)
`RATIO`	Ratio of two metrics
`CUMULATIVE`	Running total over time
`PERIOD_OVER_PERIOD`	Period comparison (YoY, MoM)

Dimension Types

Type	Description
`STRING`	Categorical text values
`INTEGER`	Whole number values
`DECIMAL`	Floating-point values
`BOOLEAN`	True/false values
`DATE`	Date only (no time component)
`TIMESTAMP`	Date and time
`TIME`	Time only (no date component)
`GEO_POINT`	Geographic coordinates
`GEO_POLYGON`	Geographic polygon shapes
`JSON`	Complex JSON objects
`ARRAY`	Array values

MDL Endpoints

Method	Path	Description
`GET`	`/api/v1/mdl`	List all MDL definitions
`GET`	`/api/v1/mdl/:mdlId`	Get an MDL definition by ID
`GET`	`/api/v1/mdl/by-name/:name`	Get the 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

Validation

Before an MDL definition can be published, it must pass validation. Validation checks include:

All referenced tables exist in the configured catalogs
Metric expressions are valid SQL aggregations
Dimension expressions reference valid columns
Relationship join keys exist in both source and target models
No circular dependencies between models

Best Practices

Define one model per logical business entity (orders, customers, products)
Use meaningful metric names that business users can understand
Mark time columns with isTimeDimension: true for temporal analysis
Validate models before publishing to catch configuration errors early
Use the versioning system to track changes to metric definitions over time

Architecture Metric Queries