cargo-segmentation

Cargo CLI — セグメンテーション

セグメントは、Cargo ワークスペースのオーディエンスレイヤーです。1つのモデルに対する名前付きの保存済みフィルターで、「どのレコードを対象にするのか」に答えます。バッチ実行、プレイのトリガー、CSV エクスポート、変更フィードなど、下流の処理はすべて、セグメント（またはセグメント形式のフィルター）を入力として使用します。

JSON レスポンスの構造全体については、references/response-shapes.md を参照してください。 よくあるエラーとその解決方法については、references/troubleshooting.md を参照してください。 フィルター条件の種類と演算子は、フィルター JSON の唯一の信頼できる情報源である ../cargo-orchestration/references/filter-syntax.md に記載されています。

セットアップ

すでにサインイン済みで（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 を標準出力に出力します。失敗すると、終了コードがゼロ以外になり、{"error": "...", "status": ..., "body": ...} が標準エラーに出力されます。実行またはバッチを作成するコマンドはすべて非同期です。--wait-until-finished を渡すか、対応する get をポーリングしてください。スキルバンドル全体がインストールされている場合は、../cargo/references/prerequisites.md に CLI のバージョン固定、トークンスコープ、管理者専用の機能が記載されています。

重要な概念

用語	説明
フィルター	1つのモデルの列に対して評価される JSON オブジェクト（{conjonction, groups[].conditions[]}）です。単独では一時的なものです。
セグメント	名前、modelUuid、slug とともに保存されたフィルターです。uuid、現在の recordsCount、履歴を持ちます。プレイ、バッチ、エクスポートが参照するのはこれです。
変更	2回の同期間におけるセグメントの計算済み差分です。added、updated、removed、unchanged の各レコード数を示します。「このオーディエンスに誰かが加わったら通知する」という動作の基礎になります。
追跡列	値の変更が updated レコードとしてカウントされる列のサブセット（--tracking-column-slugs）です。これを指定しない場合、レコードは追加または削除としてのみ記録されます。

フィルターとセグメントは、目的に応じて使い分けてください。 1回限りの質問（「従業員が100人を超える企業はいくつあるか？」）には、インラインフィルターを使った segment fetch を使用し、保存オブジェクトは作成しません。何かを実行したり、スケジュールしたり、時間の経過に伴って追跡したりする対象のオーディエンスには、実際の segment create を使用します。変更を生成できるのは、保存済みのセグメントだけだからです。

まずリソースを確認する

作成する前に、必ず一覧表示してください。通常、ワークスペースには、これから複製しようとしているセグメントがすでに存在します。

cargo-ai segmentation segment list                    # all segments (uuid, name, slug, modelUuid, recordsCount)
cargo-ai storage model list                           # find the modelUuid a segment must target
cargo-ai storage column list --model-uuid <uuid>      # the column slugs your filter conditions reference

プレイによって自動作成されるセグメントの名前は GENERATED_PLAY_SEGMENT で、fromPlay: true が設定されています。手動で編集または削除しないでください。これらは所有するプレイに属しています。

UI で確認する場合： セグメントは、app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID> のモデル配下にあります。<WORKSPACE_UUID> は cargo-ai whoami で取得してください。

クイックリファレンス

cargo-ai segmentation segment list
cargo-ai segmentation segment get <segment-uuid>
cargo-ai segmentation segment create --name "<name>" --model-uuid <uuid> --filter '<json>'
cargo-ai segmentation segment update --uuid <segment-uuid> --filter '<json>'
cargo-ai segmentation segment remove <segment-uuid>
cargo-ai segmentation segment fetch    --model-uuid <uuid> --filter '<json>' --limit 50
cargo-ai segmentation segment download --model-uuid <uuid> --filter '<json>'
cargo-ai segmentation change list  --segment-uuid <segment-uuid>
cargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50
cargo-ai segmentation record fetch --model-uuid <uuid> --ids <id[,id…]>

フィルターを作成する

すべての kind（string、number、date、boolean、array、object、objectProperty、any、vector、sql、segment、occurrence、enrollment）とすべての演算子を含む、条件の全カタログは ../cargo-orchestration/references/filter-syntax.md にあります。構造は次のとおりです。

{
  "conjonction": "and",
  "groups": [
    {
      "conjonction": "and",
      "conditions": [
        { "kind": "number", "columnSlug": "employee_count", "operator": "greaterThan", "value": 100 },
        { "kind": "string", "columnSlug": "email", "operator": "isNotEmpty" }
      ]
    }
  ]
}

conjonction であり、conjunction ではありません。 フランス語の綴りは意図的なもので、フィルターとすべてのグループの両方で必須です。キーの綴りを間違えると検証に失敗し、API は conjonction を指定して 400 を返します。呼び出しの前に、JSON 内の conjunction をすべて検索してください。

各グループには、少なくとも1つの条件が必要です。 "conditions": [] を含むグループは拒否されます（Filter groups must contain at least one condition）。すべてに一致させるには、代わりに "groups": [] を指定してください。

すべてに一致するフィルター：{"conjonction":"and","groups":[]}。

作成前にオーディエンスの規模を把握する

件数の確認は無料ですが、オーディエンスに対して何かを実行するのは無料ではありません。まず規模を確認してから、判断してください。

# 1. How many records match? — inline filter, no saved object, 1 row back; read `count`
cargo-ai segmentation segment fetch \
  --model-uuid <uuid> \
  --filter '{"conjonction":"and","groups":[{"conjonction":"and","conditions":[
      {"kind":"number","columnSlug":"employee_count","operator":"greaterThan","value":100}]}]}' \
  --fetching-limit 1 --sync false --enrich false

# 2. Happy with the shape? Save it as the real audience.
cargo-ai segmentation segment create \
  --name "Mid-market accounts" \
  --model-uuid <uuid> \
  --filter '<same json>' \
  --column-slugs "name,domain,employee_count" \
  --tracking-column-slugs "employee_count,funding_stage"

segment fetch は一致件数を count として返します（--limit ではなく --fetching-limit を使用してください。--limit はメンバー数の上限なので、--limit 1 を指定すると件数は 1 と報告されます）。続いて segment get <uuid> を実行すると、確定した規模である recordsCount が報告されます。このセグメントに対する有料の処理を提案する前に、自分で見積もった数ではなく、この数値を示してください。

fetch、download、record fetch の違い

コマンド	返される内容	用途
segment fetch --model-uuid --filter	ページネーションされたレコード（JSON 形式、--fetching-limit、--fetching-offset）	少数の行の確認、件数の確認、フィルターを保存する前のプレビュー
segment download --model-uuid --filter	データセット全体への署名付き URL（urls[]）	オーディエンス全体をユーザーまたは別のツールに渡す場合。詳しくは ../cargo-analytics/SKILL.md を参照してください
record fetch --model-uuid --ids <ids>	ID を指定した特定のレコード	変更フィードで通知された行の再取得

segment fetch は評価前にモデルを更新し（--sync）、_segments メンバーシップ列を追加します（--enrich）。省略時はどちらも有効になり、時間がかかるため、規模を確認する場合は --sync false --enrich false を指定してください。

大規模なセグメントを会話にページ分割して読み込まないでください。 --limit 3 でデータの形を確認してから、残りは download してください。

変更 — 差分フィード

セグメントが同期されるたびに、Cargo はメンバーシップの変化を変更として計算します。これにより、静的なリストがシグナルに変わります。

# What deltas exist for this segment?
cargo-ai segmentation change list --segment-uuid <segment-uuid>
# → { "changes": [ { "uuid", "totalRecordsCount", "addedRecordsCount",
#                    "updatedRecordsCount", "removedRecordsCount",
#                    "unchangedRecordsCount", "createdAt" } ] }

# Only the deltas where something entered (or moved, or left)
cargo-ai segmentation change list --segment-uuid <segment-uuid> --has-records added --limit 20

# One delta's counts, by its uuid → { "change": {...} }
cargo-ai segmentation change get <change-uuid>

# Which records actually entered the audience in that delta?
cargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50

# The whole delta as files, when it is too big to page → { "urls": [...] }
cargo-ai segmentation change download --uuid <change-uuid> --kinds added,removed

change fetch では --kinds が必須で、added、updated、removed、unchanged のいずれかを指定します（カンマ区切り）。返される行には、モデル独自の列に加えて、メタ列の _kind、_id、_title、_time が含まれます。change download は行の代わりに署名付き URL を返し、同じ 4 種類を受け付けます（unchanged は CLI 1.0.128、cargo#6369 から対応。それ以前は API が受け付けませんでした）。

change list --not-empty を指定すると、レコードが追加、更新、または削除された差分のみが残り、--has-records では 4 種類のいずれかを指定できます。どちらも CLI 1.0.128（cargo#6369）が必要です。それ以前は、API は --not-empty に対して 400（Unrecognized key: "notEmpty"）を返し、--has-records unchanged も受け付けませんでした。そのため、古い CLI では --has-records <kind> を使用して空の差分を除外してください。

セグメントの作成時に --tracking-column-slugs を指定していない限り、updatedRecordsCount は常に 0 です。追跡対象の列によって「更新」の意味が決まります。監視のワークフローに使用するセグメントでは、作成時にこれらを設定してください。

セグメントの最新の差分は segment list／segment get の結果にも lastChange としてインライン表示されるため、「何が変わったか」という質問に答えるために、追加の呼び出しが必要になることはほとんどありません。

セグメントの活用方法

セグメントは入力であり、結果ではありません。作成したら、次のように活用できます。

• セグメントに対して処理を実行する — セグメント内のすべてのレコードに対して、コネクターのアクションまたはワークフローを一括実行します：../cargo-orchestration/SKILL.md。一括処理の対象はセグメントから登録します。全対象を登録する前に、10～20件のレコードをサンプルし、明示的な承認を得てください。
• 登録時にプレイを起動する — レコードが対象に入るとプレイが実行されます。プレイは --model-uuid、--filter、--change-kinds から作成され、独自の GENERATED_PLAY_SEGMENT を生成します。詳しくは ../cargo-orchestration/references/examples/plays.md を参照してください。
• エクスポートする — ../cargo-analytics/SKILL.md（segment download には --segment-uuid ではなく --model-uuid が必要です。400 エラーのよくある原因です）。
• 監視する — 対象が空になったり、停滞したり、急増したりしたときにアラートを送信します：../cargo-observability/SKILL.md。
• GTM の対象として活用する — シグナルセグメント（転職、資金調達、テクノロジーへの関心）が ../cargo-gtm/SKILL.md のレシピを動かします。
• コードとして宣言する — 対象を git で管理する場合は、../cargo-project/SKILL.md の defineSegment を使用します。

注意点

• conjunction ではなく、conjonction を使ってください — 400 エラーで呼び出しが拒否されます。
• segment download には --segment-uuid ではなく --model-uuid が必要です。 フィルターはリクエストに含まれるため、セグメント UUID はここでは有効な入力ではありません。
• change fetch には --uuid（change の UUID）と --kinds が必要です。 セグメント UUID を渡すと 400 エラーになります。
• change list には --segment-uuid が必要です。 引数なしで呼び出すと、segmentUuid が未定義であるという 400 エラーが返されます。
• change と record のサブコマンドで --help を指定すると、サブコマンドのフラグではなく親コマンドのヘルプが表示されます（CLI ≥ 1.0.48）。上記のクイックリファレンスを使ってください。それでも問題が発生する場合は、報告してください。
• セグメントが属するモデルは1つだけです。 複数のモデルにまたがる対象は、2つのセグメントではなく、結合列に対するリレーションシップとフィルターで表現します。
• fromPlay: true のセグメントはプレイが所有します。 編集するとそのプレイの対象が変わり、削除するとプレイが動作しなくなります。
• セグメントの --limit はメンバー数を制限する値であり、表示するページサイズではありません。ページサイズには --fetching-limit を使います。

CLI が失敗した場合

同じコマンドを2回試して失敗した場合、またはこのスキルの説明と矛盾する動作があった場合は、チームに報告してください。

cargo-ai workspaceManagement report create \
  --title "<one-line summary>" \
  --description "<commands run, errorMessage verbatim, expected vs actual, UUIDs>"