Semantic Models
How Stackless defines governed measures, dimensions, joins, and business names for dashboards and Agent charting.
What is a Semantic Model?
A Semantic Model is the business-facing layer on top of warehouse data. It defines which measures and dimensions are available, how they are named, how they join, and which source relation they come from.
Dashboards and Agent chart cards rely on Semantic Models so the same metric is calculated consistently.
[picture 1. Semantic Model workspace with measures, dimensions, joins, and preview]
What Semantic Models contain
Semantic Models can include:
- A source table or published Transformation Model relation.
- Measures such as revenue, order count, active customers, margin, or conversion rate.
- Dimensions such as date, location, customer, channel, campaign, status, or product.
- Joins to related models.
- Titles and descriptions for business users.
- Source lineage back to the Catalog asset.
Use transformations as the source of truth
When business logic exists, the Semantic Model should point to the transformed relation, not the raw source table.
For example:
Raw source tables -> customers_enriched and orders_enriched -> customers and orders Semantic Models -> dashboards
This pattern keeps dashboards from reimplementing cleanup logic, dedupe logic, or joins in multiple places.
Draft and publish flow
Semantic Models can be created as drafts, previewed, and published. A draft lets you validate member names, measures, dimensions, joins, and query behavior before the model becomes shared.
Publishing a Semantic Model should happen only when:
- The source relation is stable.
- Measures and dimensions are named for business users.
- Joins are correct for the grain.
- Basic preview queries return expected rows.
- Any dependent dashboard has been reviewed.
Measures
Measures are numeric aggregations. Examples:
| Measure | Typical definition |
|---|---|
| Orders | Count of order records. |
| Net revenue | Sum of revenue after refunds, discounts, or exclusions defined by the transformation. |
| Active customers | Count of distinct customers meeting the active criteria. |
| AOV | Revenue divided by order count. |
| ROAS | Revenue divided by ad spend. |
Exact formulas vary by workspace. Use metric definitions and lineage to confirm what a measure means.
Dimensions
Dimensions describe how measures can be sliced. Examples:
- Date or timestamp.
- Location.
- Channel.
- Campaign.
- Product.
- Customer segment.
- Region or country.
- Status or category.
Dimensions should match the grain of the underlying model. If the model is daily by location, avoid exposing dimensions that imply lower-level order or line-item grain unless the relation actually supports it.
Joins
Joins let one model reference another. Use joins when dashboards need dimensions or measures across related entities, such as orders joined to customers or campaigns joined to spend.
Joins must be reviewed for grain and double-counting risk. A many-to-many join can produce inflated numbers if it is not intentionally modeled.
Agent prompts for Semantic Models
Useful prompts:
- "List the Semantic Models I can use for dashboards."
- "Show the measures and dimensions on the orders model."
- "Create a Semantic Model for the published orders_enriched transformation."
- "Preview revenue by channel using this model."
- "Explain the lineage for this dashboard KPI."
- "Check whether this metric can double-count because of joins."