How Credible Works

The parts of Credible, the path a query takes, what happens when you publish, and how organizations are isolated

Credible serves every published data model through one path: a gateway that checks each request, and Malloy Publisher, which compiles and runs the query. Around them, a control plane manages your resources, and separate services handle search and agents.

The Parts

PartWhat it does
Control planeStores and manages the organization's resources: environments, connections and their credentials, packages and versions, users, groups and permissions. You reach it through the Credible App, the cred CLI and the Admin API at <org>.admin.credibledata.com.
GatewayThe single entry point for queries, at <org>.data.credibledata.com. It authenticates each request, checks permissions, sets trusted values from the caller's identity for the model's access rules, and logs package access.
Malloy PublisherMalloy Publisher (opens in a new tab) is the open-source engine Credible maintains. It compiles Malloy to SQL, applies the model's access rules, and runs the SQL against your data through the environment's connection.
Retrieval and indexBuilds and searches the index of your models and data, which agents use to find the right sources and fields. The Retrieval API is at <org>.retrieval.credibledata.com.
Agent and MCP servicesThe in-app agent, the Slack bot, and the MCP server at <org>.mcp.credibledata.com that external AI clients connect to. They query through the same gateway as everything else.

The Query Path

Every query, whether from a person in a workspace, an MCP agent, a data app or a REST API call, takes the same path:

Workspace / agent / data app / API
        |
        v
Gateway: authenticate, authorize, set trusted values, log
        |
        v
Malloy Publisher: compile Malloy to SQL, apply access rules
        |
        v
Your data (database, warehouse or files), or a table Credible materialized
  1. The gateway identifies the organization and the caller from the caller's sign-in or API key, and checks that the caller may read the package.
  2. It routes the query to a Malloy Publisher instance that holds the requested package version. If that instance is unreachable or overloaded, the gateway retries on another one that holds the version.
  3. Malloy Publisher compiles and runs the query. Malloy compiles to SQL for your database's dialect. It applies the access rules written in the model (see Row and Column Access): a source with #(authorize) refuses callers the rule doesn't admit, and an #(access_filter) row filter is added to the compiled query, so a caller only gets the rows they are allowed to see.
  4. The query runs live or from a materialized table. By default queries run live against your data. Sources you mark for materialization are built into tables, either in your own database or in Credible-managed storage, and queries those tables cover are served from them.

Connection credentials are stored in Credible, not on anyone's machine, and consumers never connect to your database directly. Queries to your database come from Credible's stable outbound addresses, which you can allowlist (see Connect Data).

What Happens When You Publish

Publishing turns a draft or a local package directory into a new version of a package:

  1. A new version is stored. A version is never changed after it is published; publishing again creates another version. A previous version stays available until you archive it.
  2. The version is indexed and built. Credible indexes the model's exported sources, fields and documentation for search, and builds any materialized tables. This runs in the background. Queries still return correct results meanwhile; a source whose table isn't built yet is answered live.
  3. The version becomes latest, or waits. Each package has one latest version, which consumers get unless they ask for a specific one. A new package's first version becomes latest immediately. After that, auto-promote, which is on by default, makes each new version latest once it has finished indexing and building. Turn it off to set latest yourself.

Because the old latest keeps serving until a new one replaces it, consumers don't see a half-loaded model, and rolling back means setting an earlier version as latest again.

The Index

The index is what lets an agent match a question to the right part of a model by meaning, not by column name. It is built at two points:

  • Before a model exists, Credible indexes the tables you select on a connection (names, columns and types) so the modeling agent can search them.
  • After you publish, Credible indexes the model's exported sources, dimensions, measures and views, their #(doc) text, and the values of dimensions tagged #(index). See Descriptions and Value Search.

The Gateway

Every query from every surface goes through the gateway and the published model. As a result:

  • Access is checked in one place. Permissions on environments and packages, and the access rules written in the model, are checked the same way whether the caller is a person, an agent or an app. See Control Access.
  • Every package access is logged. The gateway logs each package access with the caller and the package. See Monitoring for what administrators can see.
  • Model usage is visible. Because all queries pass through the model, the engine can see which sources and fields are queried, which informs materialization and where the model needs work.

Tenancy and Isolation

Every request carries a sign-in token or a group API key, which works only for the organization it belongs to. Permissions are checked on every call, and index data is kept separate per organization.

Cloud organizations run on Credible's shared, multi-tenant deployment. Enterprise customers can run on a dedicated single-tenant deployment. See Deployment.

Next Steps

On this page