cargo-storage

Cargo CLI — Storage

データレイヤーの管理：モデル、データセット、列、リレーションシップ、統合、レコードの確認と変更、およびワークスペースストレージに対する SQL クエリの実行。

JSON レスポンスの完全な構造については、references/response-shapes.mdを参照してください。 よくあるエラーとその解決方法については、references/troubleshooting.mdを参照してください。 モデルの CRUD、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を参照してください。 取り込み（Webhook 経由）のモデルについては、references/examples/ingest-webhook.mdを参照してください。Webhook URL の導出とレコードの POST 方法が記載されています。

ブートストラップ

すでにサインイン済みで（cargo-ai whoamiがワークスペースを返す場合）は、次のセクションに進んでください。

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email [email protected]  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

すべてのコマンドは JSON を標準出力に出力します。失敗した場合は、{"errorMessage": "..."}を返してゼロ以外の終了コードで終了します。実行またはバッチを作成するコマンドはすべて非同期です。--wait-until-finishedを渡すか、対応するgetをポーリングしてください。スキルバンドル全体をインストールすると、../cargo/references/prerequisites.mdに CLI のバージョン固定、トークンスコープ、管理者専用機能が追加されます。

先にリソースを確認する

確認や変更を行う前に、必ず一覧表示してください。

cargo-ai storage dataset list              # all datasets (uuid, slug)
cargo-ai storage model list                # all models (uuid, name, slug, columns, datasetUuid)
# `model list` takes no flags — filter its output instead:
cargo-ai storage model list | jq '[.models[] | select(.datasetUuid == "<uuid>")]' 

UI で確認する場合： モデルはapp.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>にあります。<WORKSPACE_UUID>はcargo-ai whoamiのworkspace.uuidから取得します。

クイックリファレンス

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
cargo-ai storage record list --model-uuid <uuid>
cargo-ai storage record create-bulk --model-uuid <uuid> --records '[{"data":{...}}]'
cargo-ai storage model preview --dataset-uuid <uuid> --slug <extractor-slug> --config '{...}'
cargo-ai storage query execute "SELECT * FROM default.companies LIMIT 10"
cargo-ai storage query download --query "SELECT * FROM default.companies"

モデル

モデルはワークスペース内の構造化テーブルです（例：Companies、Contacts）。

# List all models
cargo-ai storage model list

# List models in a dataset — every model carries `datasetUuid`, and
# `model list` has no flags of its own, so filter client-side
cargo-ai storage model list | jq '[.models[] | select(.datasetUuid == "<uuid>")]' 

# Get a single model (includes columns)
cargo-ai storage model get <model-uuid>

# Get the DDL (full schema, table name and SQL dialect)
cargo-ai storage model get-ddl <model-uuid>
# → Useful for column discovery and SQL dialect (BigQuery vs Snowflake) before writing queries

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

# Update a model (--position moves its node on the app's data canvas)
cargo-ai storage model update --uuid <model-uuid> --name "New Name"
cargo-ai storage model update --uuid <model-uuid> --position '{"x":0,"y":0}'

# Remove a model
cargo-ai storage model remove <model-uuid>

# Is a slug taken in this dataset? → {"exists": true|false}
cargo-ai storage model exists-by-slug --dataset-uuid <uuid> --slug contacts

モデル作成前にエクストラクター設定をドライランする

model previewとmodel preview-countは、エクストラクターの設定を何も作成せずに実行します。--slugはモデルのスラッグではなく、エクストラクターのスラッグです。また、--dataset-uuidはコネクターのデータセット（kind: "connector"）を指定します。データセットはコネクターを示します。

# Sample rows + the extractor's total, for extractors that preview records
cargo-ai storage model preview \
  --dataset-uuid <connector-dataset-uuid> --slug <extractor-slug> --config '{...}'

# Count only, for extractors that preview a count
cargo-ai storage model preview-count \
  --dataset-uuid <connector-dataset-uuid> --slug <extractor-slug> --config '{...}'

各エクストラクターがサポートするのは、preview: "records"または"count"のどちらか一方（インテグレーションのエクストラクターで設定）です。もう一方を使うとエラーではなくcount: 0が返されます。どちらも試すまでは、0は「一致するものがない」という意味ではありません。previewはエクストラクターに短いドライラン用ページを要求します。クレジット制コネクターでは、そのページに表示される内容に応じて課金されます。ドライラン時の取得件数をゼロにするエクストラクター（Store LeadsのfetchDomainsなど）は課金されませんが、それ以外はアイテムごとに課金されます。料金が発生するエクストラクターをプレビューする前に、プレイブックを確認してください。無効な設定の場合は、バリデーターのメッセージとともにinvalidConfigが返されます。これはmodel createの前に設定をデバッグする最も低コストな方法です。

クエリの実行： ストレージに対して SQL を実行するには、cargo-ai storage query execute "<sql>"を使用します（完全なエクスポートにはstorage query download --query "<sql>"を使用します）。テーブルは<datasetSlug>.<modelSlug>（例：default.companies）として参照し、内部では実際のストレージテーブルに書き換えられます。詳しくは、以下のSQL でクエリを実行するを参照してください。

取り込みモデル（Webhook 経由でデータを受信）

エクストラクターの mode.kind === "ingest"（http.listenHook など）のモデルには、レコードを Cargo にプッシュしてデータを入力します。モデル設定画面には「Webhook URL」が表示されますが、CLI コマンドや API フィールドからは取得できません。ただし、CLI で既に公開されている値を使って組み立てられます。

<baseUrl>/v1/models/<model-uuid>/records/ingest?token=<api-token>

MODEL_UUID=<model-uuid>
BASE=$(cargo-ai whoami | jq -r '.baseUrl')
TOKEN=$(cargo-ai workspaceManagement token list | jq -r '.tokens[0].token')
echo "$BASE/v1/models/$MODEL_UUID/records/ingest?token=$TOKEN"

ワークフローには使用しないでください。 Cargo ワークフローでは、ネイティブの modelUpsert／modelInsert アクションを使ってモデルに書き込みます（cargo-orchestration → references/nodes.md →「ストレージ」を参照）。この URL を呼び出す HTTP ノードを使うと、ノード、ペイロード用スクリプト、ノード設定に貼り付ける API トークンが余分に必要になります。Webhook は Cargo 外部のシステム向けです。

まずエクストラクターのモードを確認してください。"autoIngest": true（calendly、smartlead、instantlyV2、heyReach、cargoSignals、explorium の listen エクストラクター）の場合、Cargo がプロバイダーにフックを登録するため、URL を共有してはいけません。全体の流れ、ペイロードの形式、制限については、references/examples/ingest-webhook.md を参照してください。

データセット

データセットはモデルを論理的にグループ化したものです。

# List all datasets
cargo-ai storage dataset list

# Get a single dataset
cargo-ai storage dataset get <dataset-uuid>

カラム

カラムはモデルのスキーマを定義します。

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

# Is a slug taken on this model? → {"exists": true|false}
cargo-ai storage column exists-by-slug --model-uuid <uuid> --column-slug <slug>

# Values a column holds ([{label, value}]) — what a filter on it can match
cargo-ai storage column autocomplete --model-uuid <uuid> \
  --column '{"slug":"industry","type":"string","label":"Industry","kind":"custom"}'

# Write custom-column values onto existing records (custom column slugs only;
# a model's own extracted fields are refused)
cargo-ai storage column insert-custom-values --model-uuid <uuid> --id <record-id> --data '{"ai_fit_score":82}'
cargo-ai storage column insert-custom-values-bulk --model-uuid <uuid> \
  --records '[{"id":"rec_1","data":{"ai_fit_score":82}},{"id":"rec_2","data":{"ai_fit_score":40}}]'

insert-custom-values を使うと、Cargo 外で計算された値（独自のパイプラインによるスコアや手動タグなど）を、コネクターと同期するモデルに追加できます。同期によって管理されるのは抽出されたフィールドで、カスタムカラムはユーザーが管理します。まずカラムを作成してください。

カラムの型：string、number、boolean、date、object、array、vector、any。

カラムの種類：custom（ユーザー定義）、computed（他のカラムを使った式）、metric（関連モデルから集計）、lookup（結合を介して関連モデルから取得する単一フィールド）。

作成した内容をプレビューする

カラムの一覧だけでは、モデルが適切かどうかはわかりません。わかるのは行データです。2 つの確認ポイントがあります（パック全体での規約は ../cargo/references/interaction.md §4 に記載されています）。

1. model create／column create の直後 — 行ではなくスキーマを表示します。 新しいモデルは空です。この時点で LIMIT 10 を実行しても何も返らず、失敗したように見えます。代わりに、カラム、型、入力される値をまとめた簡潔なテーブルを表示してください。

2. データが入ったらすぐに — 行を表示します。 バッチ、プレイ、インポートによってモデルに書き込んだ後、内容をプレビューしてください。

cargo-ai storage query execute \
  "SELECT * FROM <dataset-slug>.<model-slug> LIMIT 10"

約 10 行を表示し、意味のあるカラムだけを含めてください。ストレージへのクエリは無料なので、数行の出力だけで済みます。これはユーザーが作成した内容を実際に確認できる最初の機会です。プレイによって新しいカラムに値が入った場合は、そのカラムをレコードを特定するフィールド（name、domain）と並べてプレビューし、値が入っているかどうかがひと目でわかるようにしてください。

プレビューが空、または空であるはずがないのにすべて null の場合は、調査結果としてユーザーに知らせ、書き込みの成功を報告するだけにしないでください。原因を調べるには cargo-diagnostics を参照してください。

リレーションシップ

リレーションシップはモデル同士を関連付けます（例：コンタクトは企業に属します）。作成するには、UI だけでなく CLI を使用します。

relationship list にフラグは不要です。ワークスペース内のすべてのリレーションシップが返されます。fromModelUuid / toModelUuid でクライアント側で絞り込んでください。

cargo-ai storage relationship list

relationship set は、データセットのリレーションシップ全体を置き換えます。 データセットと、その中に存在させるリレーションシップの完全なリストを渡します。uuid を持つエントリーは更新され、持たないエントリーは作成されます。また、ペイロードに uuid がない既存のリレーションシップはすべて削除されます。5 つあるデータセットにリレーションシップを 1 つ送信すると、残りの 4 つは削除されます。必ず最初に list を実行し、追加する項目を含めた配列全体を送り返してください。

cargo-ai storage relationship set \
  --dataset-uuid <dataset-uuid> \
  --relationships '[
    {"uuid":"<existing-uuid>","fromModelUuid":"<contacts-uuid>","fromColumnSlug":"account_id","fromPropertySlug":null,"toModelUuid":"<companies-uuid>","toColumnSlug":"id","toPropertySlug":null,"fromSelectedColumnSlugs":null,"toSelectedColumnSlugs":null,"relation":"manyToOne"},
    {"fromModelUuid":"<deals-uuid>","fromColumnSlug":"company_id","fromPropertySlug":null,"toModelUuid":"<companies-uuid>","toColumnSlug":"id","toPropertySlug":null,"fromSelectedColumnSlugs":null,"toSelectedColumnSlugs":null,"relation":"manyToOne"}
  ]'

各エントリーでは、fromPropertySlug、toPropertySlug、fromSelectedColumnSlugs、toSelectedColumnSlugs が必須です（使用しない場合は null を渡します）。いずれかを省略すると、errorMessage を伴う検証エラーになります。relationship list のエントリーをコピーすれば、省略を防げます。

relation は oneToOne、manyToOne、または oneToMany です。両方のモデルが、指定するデータセット内に存在する必要があります。リレーションシップがデータセットをまたぐことはないため、応答の fromDatasetUuid と toDatasetUuid は常に --dataset-uuid と同じです。

失敗理由：datasetNotFound、invalidRelationships（解決できない列のスラッグまたはモデル UUID、あるいは重複。同じペアを逆向きに指定した場合も含む）、modelNotCompatible（以下を参照）。

統合モデルには手動でリレーションシップを設定できません。 ネイティブデータセットでは、統合モデルのリレーションシップは同期時に生成されます。そのため、fromModelUuid または toModelUuid に指定すると、modelNotCompatible が返されます。また、これらの自動生成された行は上記の置き換え処理の対象外であるため、set 呼び出しで削除することはできません。

統合

統合とは、複数のソースモデルのレコードを 1 つの正規アカウント／コンタクトにまとめることです。model update の --unification を使って、CLI から設定できます。設定を解除するには null を渡します。

# Connector-driven: the integration decides how records unify
cargo-ai storage model update --uuid <model-uuid> --unification '{"source":"integration"}'

# Custom: you name the type, the matching keys, and optionally a parent
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>"}
}'

フィールド	対象	意味
source	両方	integration（コネクターで定義）または custom
type	カスタム	account、contact、accountEvent、contactEvent
uniqueColumns	カスタム	照合キー。各列の {slug, reference} を指定します。同じ行が同一のエンティティかどうかを判定します
selectedColumnSlugs	カスタム	統合モデルに引き継ぐ列。すべての列を対象にする場合は省略します
timeColumnSlug	カスタム	イベントのタイムスタンプ。2 つの *Event タイプで使用します
parent	カスタム	コンタクト／イベントをアカウントに関連付けます：{"kind":"model","columnSlug":…,"parentModelUuid":…} または {"kind":"reference","columnSlug":…,"reference":…}
filter	カスタム	統合する行を制限するセグメンテーションフィルター。セグメントと同じ conjonction 形式です

設定を書き込んでも、データは再計算されません。 統合後の行はモデルの同期実行によって再構築されるため、更新後に実行し、完了するまでポーリングしてください。

cargo-ai storage run create --model-uuid <model-uuid>
cargo-ai storage run list --model-uuid <model-uuid>

最後に成功した同期が抽出ツールの最小間隔内にある場合、run create は upToDate で拒否されます。また、同期が進行中の場合は alreadyRunning で拒否されます。これを上書きするフラグは 2 つあります。

• --is-force true — 実行中の同期を（停止まで最大 60 秒待って）キャンセルし、データの新しさにかかわらず新しい同期を開始します。
• --is-reset true — 抽出ツールの増分カーソルをクリアし、初回同期と同様にソースからモデルを再構築します。アイテム単位の料金が発生する抽出ツールでは、結果セット全体に対して再課金されます。実行前に料金を確認してください。

現在の設定は storage model get <uuid> → unification で取得できます（モデルが統合されていない場合は null）。実行が完了したら、変更を完了として扱う前に storage query execute で行数を確認してください。uniqueColumns が狭すぎると統合が不十分になり、広すぎると別々のエンティティが統合されます。どちらの場合も、実行自体は成功したように見えます。

レコード

# List records in a model (sortable on _id, _title, or _emitted_at — the last
# only on models built from ingested records)
cargo-ai storage record list --model-uuid <uuid>
cargo-ai storage record list --model-uuid <uuid> --limit 100 --sort-column-slug _emitted_at --sort-kind desc
cargo-ai storage record get --model-uuid <uuid> --id <record-id>

# Write records — one at a time, or up to 1,000 per bulk call
cargo-ai storage record create --model-uuid <uuid> --data '{"name":"Ada","email":"[email protected]"}'
cargo-ai storage record update --model-uuid <uuid> --id <record-id> --data '{"status":"done"}'
cargo-ai storage record remove --model-uuid <uuid> --id <record-id>
cargo-ai storage record create-bulk --model-uuid <uuid> --records '[{"data":{"name":"Ada"}},{"data":{"name":"Lin"}}]'
cargo-ai storage record update-bulk --model-uuid <uuid> --records '[{"id":"rec_1","data":{"status":"done"}}]'
cargo-ai storage record remove-bulk --model-uuid <uuid> --ids '["rec_1","rec_2"]'

レコードへの書き込みは、ネイティブモデルと取り込みモデルにのみ行えます。取り込みモデルへの書き込みは、ウェブフック POST と同じ経路をたどり、エクストラクターを通るため、アイテムごとにクレジットが適用され、ペイロードの検証によってバッチが拒否される場合があります（invalidRecords）。フェッチモードのモデル（コネクターが同期するモデル）は、行が同期に属するため、書き込みを拒否し、integrationNotCompatible を返します。同期済みの行に注釈を付けるには、代わりに column insert-custom-values を使用してください。ワークフロー内では、シェルコマンドを実行するのではなく、ネイティブの modelUpsert / modelInsert アクションを使って書き込みます。

高度なレコードクエリ（フィルタリング、並べ替え、ページネーション）には、cargo-segmentation スキルの segmentation segment fetch を使用してください。

SQL でクエリする

storage query execute を使って、ワークスペースストレージに対して SQL を実行します。テーブルは <datasetSlug>.<modelSlug>（例：default.companies）で参照し、内部で基盤となるストレージテーブルに書き換えられるため、テーブル名の DDL 確認は不要です。

cargo-ai storage query execute \
  "SELECT name, domain FROM default.companies LIMIT 10"
# → { "isRefreshing": false, "rows": [...] } on success; non-zero exit with { "errorMessage": "..." } on error

全件をエクスポートするには、storage query download を使用します。CSV（デフォルト）または Parquet ファイルへの署名付き URL（urls、配列）が返されます。

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> で取得できます（ストレージ名では、追加された列に custom__ / computed__ / metric__ / lookup__ のプレフィックスが付きます）。または、storage model get-ddl <model-uuid> を実行して完全なスキーマと SQL 方言を確認してください。大きな結果セットをページ分割するには、SQL に直接 LIMIT / OFFSET を指定します。

WHERE 句、集計、結合、日付クエリ、ページネーション、エラー時に返される失敗形式については、references/examples/queries.md を参照してください。

ヘルプ

すべてのコマンドで --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