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

# Querying Cargo data

> Access your Cargo data models directly via SQL

Every data model you create in Cargo — whether an [object model](/models/object-models), an integration model, or a unified model — is stored as a table in your connected data warehouse. You can query these tables directly using SQL, whether from your own BI tools, data pipelines, or within Cargo to create new SQL-based models.

## Query from the CLI

The fastest path is `cargo-ai storage query`. Reference each model **logically** as `<dataset-slug>.<model-slug>` — Cargo validates it against your models and rewrites it to the real warehouse table, so you never hand-build a physical table name:

```bash theme={null}
cargo-ai storage model list                    # → your models and their dataset/model slugs
cargo-ai storage model get-ddl <model-uuid>    # → exact column names + types

cargo-ai storage query execute \
  "SELECT COUNT(*) AS total FROM crm.companies WHERE employee_count > 500"
# → {"outcome":"queried","rows":[{"total":142}]}
```

<Warning>
  In `storage query`, every table **must** be written as
  `<dataset-slug>.<model-slug>` (e.g. `crm.companies`) — a bare name or a physical
  warehouse name is rejected. Only `SELECT` statements are allowed. Run
  `model get-ddl` to confirm the exact column names and types before querying.
</Warning>

***

## Table naming conventions

How you name a table depends on **how** you query.

### In `cargo-ai storage query` (recommended)

Reference models logically as `<dataset-slug>.<model-slug>`:

```sql theme={null}
SELECT * FROM crm.companies      -- connector-backed model
SELECT * FROM object.accounts    -- object / unified model
```

Cargo rewrites the reference to the real warehouse table, so the same query works whether your system of record is BigQuery or Snowflake.

### Directly in your warehouse (BI tools, SQL console)

Querying the warehouse directly uses the **physical** table name, which depends on your warehouse and its configured scope. The building blocks are the schema `datasets_<connector-slug>` and the table `models_<model-slug>`:

**BigQuery**

| Scope   | Physical table                                                   |
| ------- | ---------------------------------------------------------------- |
| Dataset | `` `<project>.<dataset>.datasets_<connector>__models_<model>` `` |
| Project | `` `<project>.<prefix>_datasets_<connector>.models_<model>` ``   |

**Snowflake**

| Scope    | Physical table                                             |
| -------- | ---------------------------------------------------------- |
| Database | `<DATABASE>.datasets_<connector>.models_<model>`           |
| Schema   | `<DATABASE>.<SCHEMA>.datasets_<connector>__models_<model>` |

<Note>
  In the single-container scopes (BigQuery **dataset**, Snowflake **schema**) the
  connector and model parts are joined with a double underscore (`__`). Always
  confirm the exact physical name with `cargo-ai storage model get-ddl <model-uuid>`.
</Note>

***

## Query examples

These run through `cargo-ai storage query` using logical `<dataset>.<model>` references. To run them directly in your warehouse instead, substitute the physical table names from the conventions above.

### Basic query

```sql theme={null}
SELECT
  company,
  website,
  funding_amt,
  funding_type
FROM file.abm_raw
WHERE funding_amt > 1000000
```

### Joining multiple models

Combine data from different Cargo models:

```sql theme={null}
SELECT
  a.company,
  a.website,
  b.enrichment_data,
  c.activity_score
FROM crm.companies a
LEFT JOIN enrichment.company_data b
  ON a.domain = b.domain
LEFT JOIN analytics.scores c
  ON a.company_id = c.company_id
```

### Aggregations

```sql theme={null}
SELECT
  company,
  website,
  SUM(deal_value) as total_pipeline,
  COUNT(*) as deal_count
FROM crm.deals
WHERE stage != 'Closed Lost'
GROUP BY company, website
HAVING SUM(deal_value) > 10000
```

***

## Creating SQL models

You can create new Cargo data models by writing SQL queries against your existing tables. This is useful for combining data from multiple sources, applying transformations, or creating aggregated views.

<img src="https://mintcdn.com/cargo/tpyAGzkZkjrztY7n/images/sql-models-2.png?fit=max&auto=format&n=tpyAGzkZkjrztY7n&q=85&s=228f289990a205ae9f2cdf22c17558e3" alt="SQL model configuration" width="3024" height="1883" data-path="images/sql-models-2.png" />

<Steps>
  <Step title="Add a new SQL model">
    Navigate to your data models and create a new model. Select **SQL** as the object type.
  </Step>

  <Step title="Write your SQL query">
    Write a query that selects data from your existing Cargo tables using the naming conventions above.

    ```sql theme={null}
    SELECT
      "company",
      "_emitted_at" AS emitted_at,
      "website",
      "hq",
      "funding_amt",
      "funding_type",
      "funding_date"
    FROM CARGO_DB.datasets_file.models_abm_lk
    ```

    <Warning>
      Do not include `_id`, `_time`, `_title`, or `_segments` columns in your query—these are system columns that Cargo generates automatically. Column names also cannot start with `computed__`, `custom__`, or `metric__`, or contain `___` or `$`.
    </Warning>
  </Step>

  <Step title="Configure column mapping">
    Map the required columns:

    * **ID** — The unique identifier for each record
    * **Title** — A human-readable label for records
  </Step>

  <Step title="Preview and save">
    Preview the query results to verify your data, then save the model.
  </Step>
</Steps>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Workflows" icon="diagram-project" href="/workflows/overview">
    Use model search, record, and custom column actions.
  </Card>

  <Card title="BigQuery setup" icon="database" href="/integration/big-query">
    Configure BigQuery as your data warehouse.
  </Card>

  <Card title="Snowflake setup" icon="snowflake" href="/integration/snowflake">
    Configure Snowflake as your data warehouse.
  </Card>
</CardGroup>