Semantic Model

A semantic model captures what your data means. It sits between raw tables and everything that consumes them — dashboards, data apps, APIs, and AI agents — translating technical schemas into a shared business vocabulary: which tables matter, how they relate, and what terms like revenue and active customer actually mean.

In Credible, semantic models are written in Malloy, versioned as packages, and published from environments to every consumer at once. This page covers the concept; the Modeling Overview covers building one.

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 AI Analytics 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:

source: customers is conn.table('sales.customers') extend {
  primary_key: id
  #(doc) Sales region assigned at account creation
  dimension: region is upper(region_code)
}

source: orders is conn.table('sales.orders') extend {
  primary_key: order_id
  join_one: customers on customer_id = customers.id

  dimension: order_month is order_date.month

  #(index)
  #(doc) Net revenue recognized at order completion, in USD
  measure: total_revenue is sum(order_amount)

  view: revenue_by_region is {
    group_by: customers.region
    aggregate: total_revenue
  }
}

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 relationships
• join_many — one-to-many relationships
• join_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 like order_month above.

Measures

Measures are aggregate calculations that produce business metrics — the "how many, how much." A measure like total_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 like revenue_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 AI Analytics 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 — #@ persist materializes expensive sources so queries read pre-computed tables. See Performance & Cost.

Because annotations are part of the model's code, this metadata is version-controlled, reviewable, and published together with the definitions it describes — not maintained in a separate catalog that drifts out of date.

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

The result is an organization that speaks a common data language — consistent definitions, governed access, and AI you can trust, all from one model.

Next Steps