cargo-storage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo CLI — Storage

Cargo CLI — 存储管理

Data layer management: inspecting and modifying models, datasets, columns, relationships, and records, and running SQL queries against workspace storage.

See
references/response-shapes.md
for full JSON response structures. See
references/troubleshooting.md
for common errors and how to fix them. See
references/examples/models.md
for model CRUD, DDL inspection, and schema discovery examples. See
references/examples/datasets.md
for dataset listing and navigation examples. See
references/examples/columns.md
for column creation and management examples. See
references/examples/queries.md
for
storage query execute
/
storage query download
SQL examples (WHERE, aggregations, joins, pagination, exports).

数据层管理：检查和修改模型、数据集、列、关系和记录，并针对工作区存储运行SQL查询。

完整JSON响应结构请查看
references/response-shapes.md
。常见错误及修复方法请查看
references/troubleshooting.md
。模型增删改查、DDL检查和架构发现示例请查看
references/examples/models.md
。数据集列出和导航示例请查看
references/examples/datasets.md
。列创建和管理示例请查看
references/examples/columns.md
。
storage query execute
/
storage query download
的SQL示例（WHERE条件、聚合、连接、分页、导出）请查看
references/examples/queries.md
。

Prerequisites

前提条件

bash

npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # browser sign-in (recommended)

bash

npm install -g @cargo-ai/cli
cargo-ai login --oauth                                  # 浏览器登录（推荐）

or: cargo-ai login --token <your-api-token> # workspace-scoped API token (non-interactive)

或：cargo-ai login --token <your-api-token> # 工作区范围的API令牌（非交互式）

Pin a default workspace at login (with --oauth)

登录时固定默认工作区（使用--oauth）

cargo-ai login --oauth --workspace-uuid <uuid>


Verify with `cargo-ai whoami`. All commands output JSON to stdout. Without a global install, prefix every command with `npx @cargo-ai/cli` instead of `cargo-ai`.

Failed commands exit non-zero and return `{"errorMessage": "..."}`.

cargo-ai login --oauth --workspace-uuid <uuid>


使用`cargo-ai whoami`验证。所有命令都会将JSON输出到标准输出。如果未全局安装，请将每个命令的前缀从`cargo-ai`替换为`npx @cargo-ai/cli`。

执行失败的命令会返回非零退出码，并返回`{"errorMessage": "..."}`。

Discover resources first

先发现资源

Always list before inspecting or modifying.

bash

cargo-ai storage dataset list              # all datasets (uuid, slug)
cargo-ai storage model list                # all models (uuid, name, slug, columns)
cargo-ai storage model list --dataset-uuid <uuid>   # models in a specific dataset

Retrieve in the UI: models live at

app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>

. Get

<WORKSPACE_UUID>

from

cargo-ai whoami

under

workspace.uuid

检查或修改前请先列出资源。

bash

cargo-ai storage dataset list              # 所有数据集（uuid、slug）
cargo-ai storage model list                # 所有模型（uuid、名称、slug、列）
cargo-ai storage model list --dataset-uuid <uuid>   # 指定数据集中的模型

在UI中查看：模型位于

app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>

。可从

cargo-ai whoami

的

workspace.uuid

字段获取

<WORKSPACE_UUID>

。

Quick reference

快速参考

bash

cargo-ai storage model list
cargo-ai storage model get <model-uuid>
cargo-ai storage model get-ddl <model-uuid>
cargo-ai storage dataset list
cargo-ai storage column list --model-uuid <uuid>
cargo-ai storage relationship list --model-uuid <uuid>
cargo-ai storage record list --model-uuid <uuid>
cargo-ai storage query execute "SELECT * FROM default.companies LIMIT 10"
cargo-ai storage query download --query "SELECT * FROM default.companies"

bash

cargo-ai storage model list
cargo-ai storage model get <model-uuid>
cargo-ai storage model get-ddl <model-uuid>
cargo-ai storage dataset list
cargo-ai storage column list --model-uuid <uuid>
cargo-ai storage relationship list --model-uuid <uuid>
cargo-ai storage record list --model-uuid <uuid>
cargo-ai storage query execute "SELECT * FROM default.companies LIMIT 10"
cargo-ai storage query download --query "SELECT * FROM default.companies"

Models

模型

Models are structured tables in your workspace (e.g. Companies, Contacts).

bash

undefined

模型是工作区中的结构化表格（例如Companies、Contacts）。

bash

undefined

List all models

列出所有模型

cargo-ai storage model list

List models in a dataset

列出指定数据集中的模型

cargo-ai storage model list --dataset-uuid <uuid>

Get a single model (includes columns)

获取单个模型（包含列信息）

cargo-ai storage model get <model-uuid>

Get the DDL (full schema, table name and SQL dialect)

获取DDL（完整架构、表名和SQL方言）

cargo-ai storage model get-ddl <model-uuid>

→ Useful for column discovery and SQL dialect (BigQuery vs Snowflake) before writing queries

→ 在编写查询前，这对列发现和SQL方言（BigQuery vs Snowflake）很有用

Create a model

创建模型

cargo-ai storage model create
--slug contacts
--name "Contacts"
--dataset-uuid <uuid>
--extractor-slug <extractor-slug>
--config '{}'

Update a model

更新模型

cargo-ai storage model update --uuid <model-uuid> --name "New Name"

Remove a model

删除模型

cargo-ai storage model remove <model-uuid>


**Querying:** Use `cargo-ai storage query execute "<sql>"` (or `storage query download --query "<sql>"` for full exports) to run SQL against storage. Tables are referenced as `<datasetSlug>.<modelSlug>` (e.g. `default.companies`) and rewritten to the underlying storage table under the hood. See [Query with SQL](#query-with-sql) below.

cargo-ai storage model remove <model-uuid>


**查询**：使用`cargo-ai storage query execute "<sql>"`（或使用`storage query download --query "<sql>"`进行完整导出）针对存储运行SQL。表的引用格式为`<datasetSlug>.<modelSlug>`（例如`default.companies`），底层会自动重写为实际存储表。请参阅下方的【使用SQL查询】。

Datasets

数据集

Datasets are logical groupings of models.

bash

undefined

数据集是模型的逻辑分组。

bash

undefined

List all datasets

列出所有数据集

cargo-ai storage dataset list

Get a single dataset

获取单个数据集

cargo-ai storage dataset get <dataset-uuid>

undefined

cargo-ai storage dataset get <dataset-uuid>

undefined

Columns

列

Columns define the schema of a model.

bash

undefined

列定义了模型的架构。

bash

undefined

List columns for a model

列出模型的所有列

cargo-ai storage column list --model-uuid <uuid>

Create a column

创建列

cargo-ai storage column create
--model-uuid <uuid>
--column '{"slug":"my_column","type":"string","label":"My Column","kind":"custom"}'

Update a column (pass the full column object — columns are identified by slug, not UUID)

更新列（传入完整列对象 — 列通过slug而非UUID识别）

cargo-ai storage column update
--model-uuid <uuid>
--column '{"slug":"my_column","type":"string","label":"Updated Label","kind":"custom"}'

Remove a column

删除列

cargo-ai storage column remove --model-uuid <uuid> --column-slug <slug>

Reorder a column (move to a specific index)

重新排列列（移动到指定索引位置）

cargo-ai storage column reorder --model-uuid <uuid> --column-slug <slug> --to-index 2


Column types: `string`, `number`, `boolean`, `date`, `object`, `array`, `vector`, `any`.

Column kinds: `custom` (user-defined), `computed` (expression over other columns), `metric` (aggregated from a related model), `lookup` (single field pulled from a related model via a join).

cargo-ai storage column reorder --model-uuid <uuid> --column-slug <slug> --to-index 2


列类型：`string`、`number`、`boolean`、`date`、`object`、`array`、`vector`、`any`。

列类型分类：`custom`（用户定义）、`computed`（基于其他列的表达式）、`metric`（从关联模型聚合而来）、`lookup`（通过连接从关联模型提取的单个字段）。

Relationships

关系

Relationships link models together (e.g. Contacts belong to Companies).

bash

undefined

关系用于关联不同模型（例如Contacts属于Companies）。

bash

undefined

List relationships for a model

列出模型的所有关系

cargo-ai storage relationship list --model-uuid <uuid>

Set a relationship between two models

设置两个模型之间的关系

cargo-ai storage relationship set
--from-model-uuid <uuid>
--to-model-uuid <uuid>

undefined

cargo-ai storage relationship set
--from-model-uuid <uuid>
--to-model-uuid <uuid>

undefined

Records

记录

bash

undefined

bash

undefined

List records in a model

列出模型中的记录

cargo-ai storage record list --model-uuid <uuid>


For advanced record queries (filtering, sorting, pagination), use `segmentation segment fetch` from the `cargo-orchestration` skill.

cargo-ai storage record list --model-uuid <uuid>


如需高级记录查询（过滤、排序、分页），请使用`cargo-orchestration`技能中的`segmentation segment fetch`。

Query with SQL

使用SQL查询

Run SQL against workspace storage with

storage query execute

. Tables are referenced as

<datasetSlug>.<modelSlug>

(e.g.

default.companies

) and rewritten to the underlying storage table under the hood — no DDL lookup is needed for the table name.

bash

cargo-ai storage query execute \
  "SELECT name, domain FROM default.companies LIMIT 10"

使用

storage query execute

针对工作区存储运行SQL。表的引用格式为

<datasetSlug>.<modelSlug>

（例如

default.companies

），底层会自动重写为实际存储表 — 无需查找表名对应的DDL。

bash

cargo-ai storage query execute \
  "SELECT name, domain FROM default.companies LIMIT 10"

→ { "rows": [...] } on success; non-zero exit with { "errorMessage": "..." } on error

→ 成功时返回{ "rows": [...] }；失败时返回非零退出码及{ "errorMessage": "..." }


For full exports, use `storage query download` — it returns a signed URL to a CSV (default) or Parquet file:

```bash
cargo-ai storage query download \
  --query "SELECT name, domain, revenue FROM default.companies ORDER BY revenue DESC"

cargo-ai storage query download \
  --query "SELECT * FROM default.companies" --format parquet

Get column slugs from

storage column list --model-uuid <uuid>

(or run

storage model get-ddl <model-uuid>

for the full schema and SQL dialect). Page through large result sets with

LIMIT

OFFSET

directly in the SQL.

See

references/examples/queries.md

for WHERE clauses, aggregations, joins, date queries, pagination, and the failure shapes returned on error.


如需完整导出，请使用`storage query download` — 它会返回一个指向CSV（默认）或Parquet文件的签名URL：

```bash
cargo-ai storage query download \
  --query "SELECT name, domain, revenue FROM default.companies ORDER BY revenue DESC"

cargo-ai storage query download \
  --query "SELECT * FROM default.companies" --format parquet

可从

storage column list --model-uuid <uuid>

获取列slug（或运行

storage model get-ddl <model-uuid>

获取完整架构和SQL方言）。直接在SQL中使用

LIMIT

OFFSET

对大型结果集进行分页。

WHERE子句、聚合、连接、日期查询、分页以及错误返回格式的示例，请查看

references/examples/queries.md

。

Help

帮助

Every command supports

--help

bash

cargo-ai storage model list --help
cargo-ai storage column create --help
cargo-ai storage relationship set --help
cargo-ai storage query execute --help
cargo-ai storage query download --help

每个命令都支持

--help

参数：

bash

cargo-ai storage model list --help
cargo-ai storage column create --help
cargo-ai storage relationship set --help
cargo-ai storage query execute --help
cargo-ai storage query download --help