Give a model the schemas for orders, payments, and customers and it can quickly produce executable SQL. Ask “What was revenue last month?” and the real work begins. Does revenue mean booked value, cash received, net receipts, or recognized revenue? Which date applies? In which period do refunds belong?
Those are not universal facts for a model to infer. They are enterprise contracts. As an agent gains tools and a longer execution chain, the cost of propagating one incorrect definition into a report or action increases.
Schema describes shape. A semantic layer defines when data represents a business fact and how it may be aggregated. A model can help find conflicts or draft documentation; it cannot decide the company’s revenue policy.
Catalogs, ontologies, and semantic layers
A catalog answers what exists, where it lives, and who owns it. A semantic layer answers how a measure is calculated and which dimensions are valid. A business ontology identifies concepts such as customer, account, and order, and specifies their relationships. Execution and governance systems enforce permissions, budgets, and audit.
An ontology does not need to begin as a large knowledge graph. A governed entity model that captures keys, cardinality, validity periods, and identity mappings already prevents many join explosions and concept substitutions. The important property is that definitions are referencable, versioned, and enforceable—not that the diagram is elaborate.
Six semantic assets
| Asset | Minimum contract | Typical failure when absent |
|---|---|---|
| Metric | Formula, unit, time semantics, grain, aggregation, version, owner | Payment value is reported as recognized revenue; ratios are averaged |
| Entity | Key, uniqueness, direction, cardinality, validity | One-to-many joins inflate value; account and customer are conflated |
| Dimension | Hierarchy, valid values, applicable metrics, historical assignment | Current region is used to explain historical performance |
| Synonym | Domain, language, candidate concept, explicit non-equivalents | Revenue, sales, and cash collection collapse into one term |
| Business rule | Status filters, currency, fiscal calendar, purpose, effective dates | Test orders enter official reporting |
| Verified example | Question, semantics, query, snapshot, expectation, verifier | Old SQL remains “trusted” after the model changes |
These assets may live in a glossary, metric service, catalog, and query repository. Stable identifiers and versions must connect them. Copying prose into several systems usually creates another source of drift.
Revenue: bind meaning before generating SQL
Suppose a company maintains gross transaction value, cash received, and recognized revenue. When the user says only “revenue,” a reliable flow is:
- Check whether the current dashboard or conversation already binds a metric; otherwise clarify.
- Resolve “last month” to a concrete interval and time zone, including the applicable event time.
- Load refund, tax, currency, and internal-account rules.
- Build a semantic plan—metric, dimensions, filters, and version—before compiling a query.
A minimal contract might look like this:
{
"metric_id": "commerce.period_net_receipts",
"version": "1.0",
"definition": "successful receipts minus successful refunds in the period",
"expression": "sum(receipt_cny) - sum(refund_cny)",
"time_fields": {"receipts": "paid_at", "refunds": "refunded_at"},
"timezone": "Asia/Shanghai",
"grain": "calendar_day",
"unit": "CNY",
"allowed_dimensions": ["channel"],
"missing_input_policy": "unknown_not_zero",
"effective_from": "2026-08-01",
"test_suite_ref": "tests/net-receipts-v1"
}
Missing input remains unknown rather than becoming zero. Receipts and refunds should be aggregated to compatible grains before alignment; joining raw fact tables can multiply values. The answer should disclose the metric version, time field, data watermark, and material limitations.
How semantics enter the runtime
Semantic assets matter only when they influence execution and validation:
- Retrieval finds candidate definitions by domain, entity, and purpose, preserving conflicts.
- Planning emits a semantic plan with metric ID, version, grain, dimensions, filters, joins, and assumptions.
- Query generation compiles that plan to SQL, DAX, or another language and runs static checks.
- Execution re-enforces permission, resource, and purpose controls; a policy reference in metadata is not authorization.
- Presentation exposes the decisive definitions and limitations rather than returning a naked number.
Snowflake semantic views and Cortex Analyst show one implementation shape: semantic models describe tables, relationships, metrics, and trusted query examples for natural-language access. A vendor configuration demonstrates feasibility, not the correct definitions for another company.
Version governance matters more than more prose
Definitions need states and effective periods. Draft, in review, published, and deprecated are operationally different. A report bound to an old version must not silently move to a new formula. Adding a description may be compatible; changing formula, event time, or grain usually requires a new version and impact analysis.
Verified queries expire too. Bind them to semantic and schema versions, a data snapshot or invariant, and a named verifier. A verified query is not a piece of old SQL—it is a confirmed relationship among a question, semantics, and an executable query under stated conditions.
Evaluate invariants, not only exact outputs
A semantic test suite should cover:
- clarification for ambiguous terms and synonyms;
- grain and join cardinality;
- time boundaries, time zones, fiscal calendars, and historical dimensions;
- metric additivity, especially ratios;
- the distinction among unknown, empty set, and zero;
- compatibility and affected queries after a version change;
- valid outcomes for users with different permissions.
Metamorphic tests are especially useful. A measure that is additive over disjoint periods should equal the sum of those periods. Reordering displayed dimensions should not change the total. Adding an irrelevant filter should leave the result unchanged. These properties test business behavior more directly than exact SQL string match.
Start with one decision domain
Do not begin by modeling the whole enterprise. Choose one high-frequency decision area, govern 10–30 important metrics and their entity, time, and adjustment rules, then collect real questions and failure cases. Make BI, agents, and human analysis reference the same versions, and measure whether conflicts and rework decline.
A semantic layer is an organizational promise: within a stated context, the same term should resolve to the same explainable and reproducible business meaning. Without that promise, a stronger agent mostly packages ambiguity faster.