用 Cargo CLI 管理工作区数据层（模型、数据集、列…

当需要查看或修改 Cargo 工作区中的业务数据模型（Companies、Contacts、Deals 等）、数据集、列、关系、记录，或对工作区存储执行 SQL 查询时使用。

适用场景

解决思路

1. 先确认已登录：运行 `cargo-ai whoami` 返回工作区则跳过；否则先 `npm install -g @cargo-ai/cli`（无全局安装则每条命令前加 `npx @cargo-ai/cli`），再 `cargo-ai login --email you@company.com`（邮件验证码，无需浏览器，首次使用会创建账号），也可用 `--oauth`（浏览器）或 `--token <api-token>`（CI）；写操作前用 `cargo-ai whoami` 确认当前工作区。
2. 注意所有命令输出 JSON 到 stdout，失败时以非零退出并返回 `{"errorMessage": "..."}`；任何创建 run 或 batch 的操作都是异步的，需加 `--wait-until-finished` 或轮询对应的 `get`。
3. 始终先列出再检查或修改：`cargo-ai storage dataset list` 列出所有数据集（uuid、slug），`cargo-ai storage model list` 列出所有模型（uuid、name、slug、columns、datasetUuid）。
4. `model list` 不接受任何标志，需在客户端过滤：`cargo-ai storage model list | jq '[.models[] | select(.datasetUuid == "<uuid>")]'`。
5. 在 UI 中查看模型：访问 `app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>`，其中 `<WORKSPACE_UUID>` 从 `cargo-ai whoami` 的 `workspace.uuid` 获取。
6. 模型操作：`cargo-ai storage model list` 列出全部；`cargo-ai storage model get <model-uuid>` 获取单个模型（含列）；`cargo-ai storage model get-ddl <model-uuid>` 获取 DDL（完整 schema、表名和 SQL 方言，用于写查询前确认列和方言是 BigQuery 还是 Snowflake）；`cargo-ai storage model create --slug contacts --name "Contacts" --dataset-uuid <uuid> --extractor-slug <extractor-slug> --config '{}'` 创建；`cargo-ai storage model update --uuid <model-uuid> --name "New Name"` 更新；`cargo-ai storage model remove <model-uuid>` 删除。
7. 查询数据用 `cargo-ai storage query execute "<sql>"`，完整导出用 `cargo-ai storage query download --query "<sql>"`；表以 `<datasetSlug>.<modelSlug>` 引用（如 `default.companies`），底层会自动重写为实际存储表。
8. 处理 ingest（webhook 驱动）模型：当 extractor 的 `mode.kind === "ingest"`（如 `http.listenHook`）时，记录通过推送写入 Cargo；webhook URL 没有 CLI 命令或 API 字段直接返回，但可由已有值拼装：`<baseUrl>/v1/models/<model-uuid>/records/ingest?token=<api-token>`，其中 `BASE=$(cargo-ai whoami | jq -r '.baseUrl')`、`TOKEN=$(cargo-ai workspaceManagement token list | jq -r '.tokens[0].token')`。
9. 先检查 extractor 的 mode：当报告 `"autoIngest": true`（calendly、smartlead、instantlyV2、heyReach、cargo signals）时，Cargo 会自行向提供商注册 hook，此时不得把该 URL 分发出去。
10. 数据集操作：`cargo-ai storage dataset list` 列出全部；`cargo-ai storage dataset get <dataset-uuid>` 获取单个。
11. 列操作：`cargo-ai storage column list --model-uuid <uuid>` 列出；`cargo-ai storage column create --model-uuid <uuid> --column '{"slug":"my_column","type":"string","label":"My Column","kind":"custom"}'` 创建；`cargo-ai storage column update --model-uuid <uuid> --column '{...}'` 更新（需传完整列对象，列以 slug 而非 UUID 标识）；`cargo-ai storage column remove --model-uuid <uuid> --column-slug <slug>` 删除；`cargo-ai storage column reorder --model-uuid <uuid> --column-slug <slug> --to-index 2` 重排到指定索引。
12. 列类型：`string`、`number`、`boolean`、`date`、`object`、`array`、`vector`、`any`；列种类：`custom`（用户定义）、`computed`（基于其他列的表达式）、`metric`（从关联模型聚合）、`lookup`（通过 join 从关联模型拉取单个字段）。
13. 在 `model create` / `column create` 之后立即展示 schema 而非行：新模型为空，此时 `LIMIT 10` 返回空会被误读为失败，应把列以紧凑表格回显（列、类型、将由什么填充）。
14. 数据落地后立即预览行：在 batch、play 或 import 写入模型后运行 `cargo-ai storage query execute "SELECT * FROM <dataset-slug>.<model-slug> LIMIT 10"`，展示约 10 行且只保留有意义的列；当 play 填充新列时，把该列与记录的标识字段（`name`、`domain`）并排预览，以便看出已填与空值。
15. 若预览意外为空或全为 null，应将其作为发现上报，而不是把写入报告为成功；用 `cargo-diagnostics` 追踪原因。
16. 关系操作：`cargo-ai storage relationship list` 不接受任何标志，返回工作区中所有关系，需在客户端按 `fromModelUuid` / `toModelUuid` 过滤。
17. `relationship set` 会替换整个数据集的关系集合：带 `uuid` 的条目被更新，不带 `uuid` 的条目被创建，而 payload 中缺少其 `uuid` 的现有关系会被删除；向已有 5 个关系的数据集只发 1 个会删掉其余 4 个，因此务必先 `list`，再回传包含新增项的完整数组，例如 `cargo-ai storage relationship set --dataset-uuid <dataset-uuid> --relationships '[{"uuid":"<existing-uuid>","fromModelUuid":"<contacts-uuid>","fromColumnSlug":"account_id","toModelUuid":"<companies-uuid>","toColumnSlug":"id","relation":"manyToOne"},{"fromModelUuid":"<deals-uuid>","fromColumnSlug":"company_id","toModelUuid":"<companies-uuid>","toColumnSlug":"id","relation":"manyToOne"}]'`。
18. `relation` 取值为 `oneToOne`、`manyToOne` 或 `oneToMany`；两个模型必须位于所传数据集中，关系不能跨数据集，因此响应中的 `fromDatasetUuid` 和 `toDatasetUuid` 总等于 `--dataset-uuid`。
19. 关系失败原因：`datasetNotFound`；`invalidRelationships`（列 slug 或模型 UUID 无法解析，或重复——包括同一对关系反向表述）；`modelNotCompatible`（见下）。
20. 统一化（unify）模型拒绝手动关系：在原生数据集中，unify 模型的关系在同步期间生成，因此将其命名为 `fromModelUuid` 或 `toModelUuid` 会返回 `modelNotCompatible`；这些自动生成的行也被排除在上述替换之外，所以 `set` 调用无法删除它们。
21. 统一化可通过 `model update` 的 `--unification` 配置，传 `null` 可清除：连接器驱动用 `cargo-ai storage model update --uuid <model-uuid> --unification '{"source":"integration"}'`；自定义用 `cargo-ai storage model update --uuid <model-uuid> --unification '{"source":"custom","type":"account","uniqueColumns":[{"slug":"domain","reference":"domain"}],"selectedColumnSlugs":["name","industry","employee_count"],"parent":{"kind":"model","columnSlug":"account_id","parentModelUuid":"<accounts-uuid>"}}'`。
22. 统一化字段含义：`source` 适用于两者，取 `integration`（连接器定义）或 `custom`；`type` 仅 custom，取 `account`、`contact`、`accountEvent`、`contactEvent`；`uniqueColumns` 仅 custom，是匹配键，每列 `{slug, reference}`，决定哪些行属于同一实体；`selectedColumnSlugs` 仅 custom，是带入统一模型的列，省略则全部；`timeColumnSlug` 仅 custom，是事件时间戳，用于两个 `*Event` 类型；`parent` 仅 custom，把联系人/事件链接到其账户，形如 `{"kind":"model","columnSlug":…,"parentModelUuid":…}` 或 `{"kind":"reference","columnSlug":…,"reference":…}`；`filter` 仅 custom，是限制哪些行参与统一的分段过滤器，与 segments 的 `conjonction` 形状相同。
23. 写入统一化配置不会重算任何东西：统一行由模型的 sync run 重建，因此更新后要跟一次运行并轮询：`cargo-ai storage run create --model-uuid <model-uuid>` 和 `cargo-ai storage run list --model-uuid <model-uuid>`。
24. 从 `storage model get <uuid>` → `unification` 获取当前配置（模型不统一时为 `null`）；运行完成后用 `storage query execute` 检查行数再视为完成——`uniqueColumns` 过窄会欠合并，过宽会合并掉不同实体，两者都表现为运行成功。
25. 记录操作：`cargo-ai storage record list --model-uuid <uuid>` 列出记录；更高级的记录查询（过滤、排序、分页）使用 `cargo-orchestration` 技能中的 `segmentation segment fetch`。
26. SQL 查询：`cargo-ai storage query execute "SELECT name, domain FROM default.companies LIMIT 10"` 成功返回 `{ "rows": [...] }`，出错时非零退出并返回 `{ "errorMessage": "..." }`；完整导出用 `cargo-ai storage query download --query "SELECT name, domain, revenue FROM default.companies ORDER BY revenue DESC"`，返回 CSV（默认）或 Parquet 文件的签名 URL，可用 `--format parquet` 指定格式。
27. 列 slug 从 `storage column list --model-uuid <uuid>` 获取，或运行 `storage model get-ddl <model-uuid>` 获取完整 schema 和 SQL 方言；大结果集直接在 SQL 中用 `LIMIT` / `OFFSET` 分页。
28. 每个命令都支持 `--help`，如 `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`。

适用边界 · 注意事项

• 查询运行或批处理遥测而非业务数据时——应使用 cargo-orchestration。
• 命名可复用的过滤受众时——应使用 cargo-segmentation。