Skip to main content
A semantic model captures what your data means — sources connected to your tables, joins between them, and the dimensions, measures, and views that encode your business definitions — as Malloy code in a versioned package. You build models with AI agents: describe what you want in plain language, and the agent discovers your data, drafts the model, and helps you validate and publish it. As covered in Environments, there are two ways to build. Build & Publish in the app is the fastest way to get started — the in-app agent handles everything from connecting data to publishing, with nothing to install. Local Development brings the same capabilities to your IDE and coding agent for Git-based workflows and direct control over files. Both produce the same governed packages, and this section applies to both.
New to semantic modeling? See What is a Semantic Layer? to understand the concepts, or the Malloy Language Documentation for language details.

​
The Building Blocks

A Malloy model is built from a handful of constructs. You’ll see them in everything the agent generates:
  • Sources — tables from your environment’s connections, extended with semantics: source: orders is conn.table('sales.orders') extend { ... }
  • Joins — relationships between sources, declared once and available to every query
  • Dimensions — attributes to group and filter by
  • Measures — aggregate calculations like revenue or order count, defined once and reused everywhere
  • Views — saved query patterns built from dimensions and measures
  • Annotations — tags on sources and fields that tell Credible how to treat them. Annotations are how you evolve a model beyond its logical definition: #(doc) documents a field, #(index) makes its values searchable, #(authorize) controls who can query a source, and #@ persist materializes it for performance. The rest of this section is largely about applying them.

​
Stages of Model Development

A model matures in stages, and the pages in this section follow them in order:
  1. Model — build the logical model: sources, joins, dimensions, measures, and views (this page)
  2. Optimize for AI retrieval — document fields and index values with Discovery tags so agents find and understand your data
  3. Secure — control who sees which sources, rows, and columns with fine-grained Access Control annotations
  4. Optimize performance and cost — materialize expensive sources and manage index freshness with persistence annotations (Performance & Cost)
  5. Publish — version and serve the model to every consumer with Publishing
You don’t have to do them all at once — a first model can go straight from stage 1 to publish, then pick up retrieval, security, and performance annotations as it evolves.

​
Prerequisites

The agent only knows about your data after the connection is indexed — this is configured when you set up the connection’s scope. Indexing can take a few minutes, so if the agent can’t see a new connection’s tables yet, wait and check that your tables are within the indexing limits.

​
Build a Model with the Agent

The workflow is the same whether you’re chatting in the app or in your IDE:
  1. Describe what you want to model. Be specific about your data and analysis goals:
    • “Build a model of my ecommerce data so I can analyze sales by product and brand”
    • “Create a semantic model for customer analytics including lifetime value”
    • “Model the orders table with customer and product relationships”
  2. The agent discovers and proposes. Using its MCP (Model Context Protocol) tools, the agent explores your indexed tables and schemas, then proposes — backed by real data — which tables to include, how they join, and which dimensions and measures to define. Credible’s open-source agent skills — curated in the open with the world’s data experts — guide it to follow Malloy best practices automatically. The same skills run on every surface, so the workflow is identical in the app and in your IDE.
  3. Confirm and iterate. Approve or adjust each proposal in plain language, and the agent writes the model — every field defined, documented with #(doc), and indexed with #(index) where it helps discovery. In the app, the agent previews queries in the chat so you see real results at each step; in your IDE, review the generated .malloy files and approve the changes.

​
Validate as You Build

Preview results against real data before you publish:
  • In the app — the agent runs queries against the draft package and shows results in the chat; open the draft at any time to browse the generated files
  • In your IDE — use the buttons above each source definition: Schema to view the compiled structure, Explore to interactively query in the Explorer, and Preview for a quick data check

​
Next Steps

Continue through the stages, or jump straight to publishing your first model:

Discovery

Document and index your model so agents find and understand your data

Publish Your Model

Make your model available across the platform