> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Modeling Overview
> Build semantic models with AI agents — in the app or in your IDE
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](https://malloydata.dev) 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](/how-to/modeling/environment-overview), there are two ways to build. [Build & Publish](/how-to/modeling/in-app-development) 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. The [developer tools](/how-to/developers/overview) bring 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 [Semantic Model](/concepts/semantic-layer) to understand the concepts, or the [Malloy Language Documentation](https://docs.malloydata.dev/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 Metadata](/how-to/modeling/metadata-tags) tags so agents find and understand your data
3. **Secure** — control who sees which sources, rows, and columns with fine-grained [Access Control](/how-to/modeling/fine-grained-acls) annotations
4. **Optimize performance and cost** — materialize expensive sources and manage index freshness with persistence annotations ([Performance & Cost](/how-to/modeling/persistence))
5. **Publish** — version and serve the model to every consumer with [Publishing](/how-to/modeling/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
* **A place to build** — a [workspace in the Credible App](/how-to/modeling/in-app-development), or an [IDE with the Credible Extension](/how-to/developers/vscode-extension)
* **A database connection** — see [Connect a Database](/how-to/modeling/connect-data)
The agent only knows about your data after the connection is indexed — this is configured when you [set up the connection's scope](/how-to/modeling/connect-data#configure-scope-for-ai-assisted-modeling). 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:
**Already have a BI tool or a semantic layer?** If your business logic lives in Looker, Power BI, Tableau, Cube, dbt, or a warehouse semantic view, give the agent that context rather than starting from a blank file — it reads your existing definitions for intent and rebuilds them as governed Malloy, which is usually faster and more faithful than describing the model from memory. See [Migrations](/how-to/migrating/overview).
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](/introduction#one-set-of-skills-every-surface) — 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](https://docs.malloydata.dev/documentation/user_guides/publishing/explorer), and **Preview** for a quick data check
## Next Steps
Continue through the stages, or jump straight to publishing your first model:
Document and index your model so agents find and understand your data
Make your model available across the platform