Why Semantic Models Matter
Modern organizations have data spread across many systems — sales in the CRM, marketing in analytics tools, finance in the ERP — and each system, team, and dashboard tends to develop its own definitions of key metrics. When “monthly revenue” is computed five different ways, the numbers disagree, meetings turn into debates about whose figure is right, and trust in data erodes. A semantic model fixes this at the root: every metric, relationship, and business rule is defined once, in one place, and reused everywhere. The model also acts as a data contract between producers and consumers. Engineering teams evolve schemas, migrate warehouses, and refactor pipelines behind the model; analysts, applications, and agents query stable business definitions in front of it. When the underlying systems change, the contract holds — reports and applications keep working. AI raises the stakes. An agent answers in seconds, at scale, to people who may not know enough to question the result — so definitions that drift or logic that’s subtly wrong become visible immediately. A semantic model is what makes AI trustworthy: instead of guessing at raw schemas, the agent works from your governed definitions, and every answer is consistent with what humans see in dashboards. This is the foundation Credible’s Context Engine is built on.Anatomy of a Semantic Model
A semantic model is built from a handful of constructs. Here’s a compact but complete example:Sources
Sources are datasets extended with business logic — the reusable building blocks of the model. A source wraps a table (or another source) and attaches everything the organization knows about it: keys, relationships, definitions, and metadata.Joins
Joins declare how sources relate, once, with explicit business meaning —orders join one customer. Every query can then traverse the relationship without restating join conditions, and Malloy’s aggregate handling guarantees that joined queries never double-count.
join_one— one-to-one or many-to-one relationshipsjoin_many— one-to-many relationshipsjoin_cross— cartesian products (used sparingly)
Dimensions
Dimensions are the attributes you group and filter by — the “who, what, when, where” of your data. They range from simple column references to derived fields, categorizations, and date transformations likeorder_month above.
Measures
Measures are aggregate calculations that produce business metrics — the “how many, how much.” A measure liketotal_revenue is defined once on its source and means exactly the same thing in every query, dashboard, and AI-generated answer that references it.
Views
Views are saved query patterns — curated combinations of dimensions, measures, and filters likerevenue_by_region. They encode the analyses your organization actually runs, giving consumers (and agents) proven starting points instead of blank pages.
Filters
Filters restrict data to relevant subsets and can be applied at every level — source-wide (a source of only completed orders), within a view, or on a single measure (revenue from enterprise customers only).Annotations & Metadata
Annotations are tags that layer metadata onto the logical model — documentation, discovery hints, access rules, and performance directives, living next to the data they describe:- Documentation & discovery —
#(doc)describes a field in business terms and#(index)makes its values searchable, powering the Context Engine so agents can find and understand your data. See Discovery Metadata. - Access control —
#(authorize)and secure givens define row- and column-level security in the model itself, enforced on every surface. See Access Control. - Performance & cost —
#@ persistmaterializes expensive sources so queries read pre-computed tables. See Performance & Cost.
From Schema to Semantic Graph
A database schema permits every join its foreign keys allow — a natural graph where most paths are meaningless or dangerous, and nothing distinguishes the join an analyst should use from the one that silently double-counts. Modeling transforms that into a curated semantic graph: only meaningful business relationships, each declared with explicit intent. This curation is where the value comes from. It eliminates ambiguity (one right way to connect orders to customers), enables governance (definitions and access rules attach to the graph), and makes data explorable — a business user or an AI agent can navigate the model without knowing anything about the underlying schema.Models Are Versioned Packages
In Credible, a semantic model doesn’t live loose — it ships as a package: model files, data apps, and a manifest, versioned together and published from an environment. This brings the software lifecycle to data:- One model, every consumer — a published package serves workspace chat, data apps, MCP agents, and the REST APIs from the same definitions
- Safe evolution — new versions publish atomically; data apps are versioned with the models they’re built on, so a model change never breaks a dashboard mid-flight
- Accountability — every definition traces to a reviewed, version-controlled change
Next Steps
Modeling Overview
Start building semantic models with AI agents
Why Malloy?
The open-source language semantic models are written in
Platform Architecture
How Credible implements and serves semantic models
Governance
How governance becomes the path of least resistance