Skip to main content
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. 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
ScopePhysical table
Dataset`<project>.<dataset>.datasets_<connector>__models_<model>`
Project`<project>.<prefix>_datasets_<connector>.models_<model>`
Snowflake
ScopePhysical 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. SQL model configuration
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.