Model Your Data

How data modeling works in Credible, the two ways to build a model (in the Credible App or with your coding agent), the draft to publish lifecycle, and how a larger model is organized

A data model in Credible is Malloy (opens in a new tab) code that says what your data means: sources over your tables, the joins between them, and the dimensions, measures and views that hold your business definitions. For what belongs in a model and why, see The Data Model. For the language, see the Malloy documentation (opens in a new tab).

What You Build

You build a package: a folder of Malloy files with a publisher.json manifest. A package can also carry reports (dashboards and notebooks), data apps and small data files. It is published and versioned as one unit, so the model, its documentation, its access rules and the apps built on it move together. Publishing and Versions covers the package layout and the manifest.

Each package lives in an environment, which holds the database connections the package reads from.

Two Ways to Build

You work with the agent the same way in both: describe what you want, review its proposals and publish when you're ready. Both produce the same kind of package, and the agent follows the same open-source modeling skills. What differs is where the files live and how you set up.

WaySet upUse it when
In the Credible AppNothing to install. Start a chat; the agent works in a draft package and publishes it when you ask.You want to start quickly, or the people modeling don't use an IDE.
With your coding agentClaude Code, Codex, Cursor and others, in your own editor. Run cred init in a directory to install the modeling skills and a local Publisher (see Cred CLI), or use the VS Code Extension. The model is the files in the directory.You want the files on your machine and in your own Git repository, or to publish from CI/CD.

To have each publish from the app reviewed as a pull request, use a git-backed environment.

Either way, the agent acts with your role, so it can't do anything you couldn't do yourself. Connection credentials stay in Credible, so it never sees them.

The Model Lifecycle

Every model goes through the same four stages, wherever you build it:

  1. Draft. Changes are made in a working copy that nobody else queries. In the app this is a draft package; with your coding agent it is the files in your project directory, served by a local Publisher.
  2. Preview. The agent compiles the model on every edit and runs queries against the draft, so you check results against real data before anyone else sees them.
  3. Publish. Publishing creates a new, immutable version of the package. Credible then builds the version's search indexes and any materialized tables. See What Happens When You Publish.
  4. Serve. The version marked as latest is what workspaces, reports, data apps, AI agents over MCP and the APIs query by default. Older versions stay available until they are archived, so you can roll back.

Build a Model with the Agent

The steps, from describing the outcome to publishing, are in Build a Model. Moving from a BI tool or a semantic layer? Give the agent your existing definitions instead of describing the model from memory: see Migrate to Credible.

The Shape of a Data Model

A small model fits in one source. A larger one organizes its sources in three layers:

LayerWhat it holdsWho queries it
Analytical domainsOne source per access decision, derived from the core, with viewsEvery caller: people, dashboards, data apps and agents
The coreThe joins, and every definition more than one domain usesNobody directly
Base sourcesOne source per table: its grain, plus definitions that need only its columnsNobody directly

Callers only query the top layer, so that is where access rules go and what the package's index.malloy exports (see Exports and Field Visibility). The examples below model a support team's tickets, from the bottom layer up.

Base Sources

One source per table. primary_key declares the grain, one row per ticket, which lets Malloy aggregate correctly across joins. Add definitions that need only this table's columns, such as unit conversions and flags. Anything that reaches another table belongs in the core.

In base.malloy:

source: tickets_raw is warehouse.table('support.tickets') extend {
  primary_key: ticket_id

  dimension:
    first_response_hours is first_response_minutes / 60
    is_open is status = 'open'
}

source: accounts_raw is warehouse.table('crm.accounts') extend {
  primary_key: account_id

  dimension:
    tenant_slug is lower(tenant_name)
}

source: agents_raw is warehouse.table('support.agents') extend {
  primary_key: agent_id
}

The Core

The joins, and the definitions that must mean the same thing in every domain. join_one attaches a related source with at most one match per row. open_ticket_count reuses is_open from the base source instead of repeating status = 'open'.

In core.malloy:

import "base.malloy"

source: ticket_core is tickets_raw extend {
  join_one: account is accounts_raw on account_id = account.account_id
  join_one: assignee is agents_raw on assigned_agent_id = assignee.agent_id

  dimension:
    tenant is account.tenant_slug
    segment is account.segment

  measure:
    ticket_count is count()
    open_ticket_count is count() { where: is_open }
    avg_first_response_hours is first_response_hours.avg()
}

Analytical Domains

The sources callers query. Each domain's access rules apply to everyone who queries it, so create one domain per access decision, and split a domain wherever two audiences need different answers. is ticket_core extend inherits everything the core defines, and a view saves a query shape so callers don't rewrite it.

In support_performance.malloy:

import "core.malloy"

source: support_performance is ticket_core extend {
  view: backlog_by_priority is {
    group_by: priority
    aggregate: open_ticket_count
  }
}

Changing the Model

A definition lives in one place. Change it there and publish, and everything derived from it (search indexes, materialized tables, access enforcement, the context agents receive) follows in the new version. To roll back, mark the previous version as latest; see Serving and Version Management.

Every annotation Credible reads in a model, from #(doc) to #@ preaggregate, is listed in Annotations.

Next Steps

On this page