Querying Cargo data

Access your Cargo data models directly via SQL

Every data model you create in Cargo — whether an object model, 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:

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}]}

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.

---

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

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>

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

---

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

SELECT
  company,
  website,
  funding_amt,
  funding_type
FROM file.abm_raw
WHERE funding_amt > 1000000

Joining multiple models

Combine data from different Cargo models:

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

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.

1. Add a new SQL model

   Navigate to your data models and create a new model. Select SQL as the object type.

2. Write your SQL query

   Write a query that selects data from your existing Cargo tables using the naming conventions above.

   SELECT
     "company",
     "_emitted_at" AS emitted_at,
     "website",
     "hq",
     "funding_amt",
     "funding_type",
     "funding_date"
   FROM CARGO_DB.datasets_file.models_abm_lk
   

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

3. Configure column mapping

   Map the required columns:

   • ID — The unique identifier for each record
   • Title — A human-readable label for records
4. Preview and save

   Preview the query results to verify your data, then save the model.

---

Next steps

Workflows

Use model search, record, and custom column actions.

BigQuery setup

Configure BigQuery as your data warehouse.

Snowflake setup

Configure Snowflake as your data warehouse.