Overview

Structured, queryable tables that power your plays and workflows. Define them in code with defineModel, sourced from a connector or owned by Cargo.

A data model is a structured table in your Cargo warehouse. Models feed play triggers, back model-search steps, and give agents structured context. You define them in code with defineModel.

Define a model

A model sourced from a connector’s dataset wires to the connector by handle and pulls rows with an extractor:

models/contacts.ts

import { defineModel } from "@cargo-ai/cdk";
import { hubspot } from "../connectors/hubspot";

export const contacts = defineModel("contacts", {
  connector: hubspot,            // handle — connector deploys first, dataset injected
  extractSlug: "fetchRecords", // which connector action populates the table
  config: { objectType: "contacts", columnSelectionMode: "all" },
  schedule: { type: "cron", cron: "0 * * * *" }, // refresh hourly
});

See Extractors for how a connector action becomes a model’s data source.

Model types

Models live side-by-side in the same warehouse and can be queried, joined, and used as triggers. What differs is who owns the schema and who writes the rows.

Type	Schema owner	Writable from a workflow	Typical use
Object	You (built-in or custom)	Yes	Sourced lists, internal pipelines, custom entities
Integration	The connected source	No — use the integration’s write actions	Mirror CRM, warehouse, webhook, or file data
Unified	Cargo	Read-only	One deduplicated view of accounts, contacts, and events

• Object models — native, writable Account / Contact / Deal / Lead or custom schemas.
• Unification — read-only merged views across all sources.
• Querying data — SQL over your models.
• Segments — named, filtered views defined with defineSegment.
• Activities — event models.

Capabilities

• Change-based triggers — plays react in real time to added / updated / removed rows.
• Segments — named, filtered views that batches, exports, and plays target.
• Relationships — join models on shared columns with defineRelationship.
• Additional columns — custom, computed, and metric columns extend a model without touching the source.

From the CLI

cargo-ai storage model list                  # → modelUuid
cargo-ai storage model get-ddl <model-uuid>  # exact SQL table name
cargo-ai storage model refresh <model-uuid>

Using the UI

Build the same models in the web app — see Using the UI for the visual walkthrough of object models, integration loaders (native, webhook, SQL), and relationships.

Cargo hosts your models on a data warehouse. By default you get a managed Snowflake instance, or connect your own — see Snowflake and BigQuery.