> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following every step in https://api.getcargo.io/agent-install.txt` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://github.com/getcargohq/cargo-skills/blob/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# 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**:

```ts models/contacts.ts theme={null}
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](/models/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](/models/object-models) — native, writable `Account` / `Contact` / `Deal` / `Lead` or custom schemas.
* [Unification](/models/unification) — read-only merged views across all sources.
* [Querying data](/models/querying) — SQL over your models.
* [Segments](/models/segments) — named, filtered views defined with `defineSegment`.
* [Activities](/models/activities) — event models.

## Capabilities

* **Change-based triggers** — plays react in real time to added / updated / removed rows.
* **[Segments](/models/segments)** — named, filtered views that batches, exports, and plays target.
* **[Relationships](/models/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

```bash theme={null}
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](/models/using-ui) for the visual walkthrough of object models, integration loaders (native, webhook, SQL), and relationships.

<Note>
  Cargo hosts your models on a data warehouse. By default you get a managed
  Snowflake instance, or connect your own — see [Snowflake](/integration/snowflake)
  and [BigQuery](/integration/big-query).
</Note>