Skip to main content
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", {
  dataset: 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.
TypeSchema ownerWritable from a workflowTypical use
ObjectYou (built-in or custom)YesSourced lists, internal pipelines, custom entities
IntegrationThe connected sourceNo — use the integration’s write actionsMirror CRM, warehouse, webhook, or file data
UnifiedCargoRead-onlyOne 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 identifiers.
  • 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.