> ## 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.

# 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", {
  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](/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** — join models on shared identifiers.
* **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>