cargo-segmentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo CLI — Segmentation

Cargo CLI — Segment 管理

Segments are the audience layer of a Cargo workspace: a named, saved filter over one model that answers "which records do I mean?" Everything downstream — a batch run, a play trigger, a CSV export, a change feed — takes a segment (or a segment-shaped filter) as its input.

See
references/response-shapes.md
for full JSON response structures. See
references/troubleshooting.md
for common errors and how to fix them. Filter condition kinds and operators live in
../cargo-orchestration/references/filter-syntax.md
— the single source of truth for filter JSON.

Segment是Cargo工作区的受众层：它是针对单个模型的命名已保存筛选器，用于明确“我指的是哪些记录？”。所有下游操作——批量运行、Play触发器、CSV导出、变更推送——都以Segment（或Segment格式的筛选器）作为输入。

完整JSON响应结构请查看
references/response-shapes.md
。常见错误及修复方法请查看
references/troubleshooting.md
。筛选器条件类型和运算符定义在
../cargo-orchestration/references/filter-syntax.md
中——这是筛选器JSON的唯一权威来源。

Bootstrap

初始化

Already signed in (

cargo-ai whoami

returns a workspace)? Skip to the next section.

bash

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # 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

Every command prints JSON to stdout; failures exit non-zero with

{"errorMessage": "..."}

. Anything that creates a run or a batch is async — pass

--wait-until-finished

or poll the matching

get

. When the full skill bundle is installed,

../cargo/references/prerequisites.md

adds the CLI version pin, token scopes, and the admin-only surface.

已登录（

cargo-ai whoami

返回工作区信息）？请跳至下一节。

bash

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                         # 执行任何写入操作前，确认当前激活的工作区

所有命令都会向标准输出打印JSON；执行失败时会以非零状态码退出，并返回

{"errorMessage": "..."}

。所有创建运行任务或批量任务的操作都是异步的——可添加

--wait-until-finished

参数等待完成，或轮询对应的

get

命令。安装完整技能包后，

../cargo/references/prerequisites.md

会包含CLI版本固定、令牌权限范围以及管理员专属功能的说明。

Key concepts

核心概念

Term	What it is
Filter	A JSON object ( `{conjonction, groups[].conditions[]}` ) evaluated against one model's columns. Ephemeral on its own.
Segment	A filter saved with a name, a `modelUuid` , and a `slug` . Has a `uuid` , a live `recordsCount` , and a history. This is what plays, batches, and exports reference.
Change	One computed delta of a segment between two syncs — how many records were `added` , `updated` , `removed` , `unchanged` . The basis of every "notify me when someone enters this audience" motion.
Tracking columns	The subset of columns ( `--tracking-column-slugs` ) whose value changes count as an `updated` record. Without them a record only ever registers as added or removed.

Filter vs segment — pick deliberately. A one-off question ("how many companies have >100 employees?") wants

segment fetch

with an inline filter and no saved object. An audience you will run something against, schedule against, or track over time wants a real

segment create

— because only a saved segment produces changes.

Term	定义
Filter	一个JSON对象（ `{conjonction, groups[].conditions[]}` ），用于对单个模型的列进行评估，本身为临时对象。
Segment	已保存的筛选器，包含名称、 `modelUuid` 和 `slug` 。拥有 `uuid` 、实时 `recordsCount` 以及历史记录，是Play、批量任务和导出操作的引用对象。
Change	两次同步之间Segment的计算差值——记录的 `added` （新增）、 `updated` （更新）、 `removed` （移除）、 `unchanged` （未变更）数量。是“当有用户进入该受众时通知我”这类场景的基础。
Tracking columns	列的子集（通过 `--tracking-column-slugs` 指定），其值变化会被标记为 `updated` 记录。若未指定，记录只会被标记为新增或移除。

筛选器与Segment的选择——需谨慎决策。一次性查询（如“员工数>100的公司有多少家？”）适合使用

segment fetch

并传入内联筛选器，无需保存对象。若受众需用于执行任务、调度或长期跟踪，则需创建真正的

segment create

——只有已保存的Segment才会产生变更记录。

Discover resources first

先发现已有资源

Always list before creating. A workspace usually already holds the segment you are about to duplicate.

bash

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

Segments created automatically by a play are named

GENERATED_PLAY_SEGMENT

and carry

fromPlay: true

— never edit or remove those by hand; they belong to the play that owns them.

Retrieve in the UI: segments live under the model at

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

. Get

<WORKSPACE_UUID>

from

cargo-ai whoami

创建前务必先列出已有内容。工作区中通常已经存在你想要创建的同类Segment。

bash

cargo-ai segmentation segment list                    # 列出所有Segment（包含uuid、name、slug、modelUuid、recordsCount）
cargo-ai storage model list                           # 查找Segment必须关联的modelUuid
cargo-ai storage column list --model-uuid <uuid>      # 筛选器条件引用的列slug

由Play自动创建的Segment命名为

GENERATED_PLAY_SEGMENT

，并带有

fromPlay: true

标记——切勿手动编辑或删除此类Segment；它们属于创建它们的Play。

在UI中查看：Segment位于模型页面，地址为

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

。可通过

cargo-ai whoami

获取

<WORKSPACE_UUID>

。

Quick reference

快速参考

bash

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…]>

bash

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…]>

Building a filter

构建筛选器

The full condition catalogue — every

kind

(

string

number

date

boolean

array

relation

) and every operator — is in

../cargo-orchestration/references/filter-syntax.md

. The shape:

json

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

conjonction
, not
conjunction
. The French spelling is intentional and it is the single most expensive typo in the CLI: a misspelled key does not error — the filter silently matches nothing, and you conclude the data is empty. Grep your JSON for
conjunction
before every call.

Match-everything filter:

{"conjonction":"and","groups":[]}

完整的条件目录——包括所有

kind

（

string

、

number

、

date

、

boolean

、

array

、

relation

）和运算符——请查看

../cargo-orchestration/references/filter-syntax.md

。筛选器结构如下：

json

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

注意：是
conjonction
，而非
conjunction
。这是特意使用的法语拼写，也是CLI中代价最高的拼写错误：拼写错误不会触发报错——筛选器会静默匹配不到任何记录，你会误以为数据为空。每次调用前，请检查JSON中的拼写是否为
conjonction
。

匹配所有记录的筛选器：

{"conjonction":"and","groups":[]}

。

Size the audience before you build it

构建前先估算受众规模

Counting is free; running anything over an audience is not. Establish the size first, then decide.

bash

undefined

计数是免费的；但针对受众执行操作会产生成本。先确认受众规模，再做决策。

bash

undefined

1. How many records match? — inline filter, no saved object, 1 row back

1. 有多少条记录匹配？——使用内联筛选器，无需保存对象，返回1行结果

cargo-ai segmentation segment fetch
--model-uuid <uuid>
--filter '{"conjonction":"and","groups":[{"conjonction":"and","conditions":[ {"kind":"number","columnSlug":"employee_count","operator":"greaterThan","value":100}]}]}'
--limit 1

2. Happy with the shape? Save it as the real audience.

2. 对结果满意？将其保存为正式受众。

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 get <uuid>` then reports `recordsCount` — the authoritative size. Cite that number, not your own estimate, before proposing a paid run over the segment.


执行`segment get <uuid>`后会返回`recordsCount`——这是权威的受众规模。在提议针对该Segment执行付费任务前，请引用此数值，而非自行估算。

Fetch vs download vs record fetch

Fetch、Download与Record Fetch的区别

Command	Returns	Use for
`segment fetch --model-uuid --filter`	Records inline as JSON, paginated ( `--fetching-limit` , `--fetching-offset` )	Inspecting a handful of rows, counting, previewing a filter before saving it
`segment download --model-uuid --filter`	A signed URL to the full dataset	Handing the whole audience to the user or another tool — see `../cargo-analytics/SKILL.md`
`record fetch --model-uuid --ids <ids>`	Specific records by id	Re-reading rows a change feed just told you about

segment fetch --sync

refreshes the underlying data sources before evaluating;

--enrich

returns joined/derived values. Both cost time, so leave them off for a size check.

Never page a large segment into the conversation. Use

--limit 3

to see the shape, then

download

for the rest.

命令	返回内容	使用场景
`segment fetch --model-uuid --filter`	以JSON格式返回分页记录（可通过 `--fetching-limit` 、 `--fetching-offset` 参数控制）	检查少量数据行、计数、保存前预览筛选器效果
`segment download --model-uuid --filter`	完整数据集的签名URL	将整个受众数据交付给用户或其他工具——请查看 `../cargo-analytics/SKILL.md`
`record fetch --model-uuid --ids <ids>`	指定ID的具体记录	重新读取变更推送刚通知的行数据

segment fetch --sync

会在评估前刷新底层数据源；

--enrich

会返回关联/衍生值。这两个操作都会耗时，因此仅做规模检查时请关闭它们。

切勿对大型Segment进行分页查询。使用

--limit 3

查看数据结构，然后使用

download

获取完整数据。

Changes — the delta feed

变更记录——差值推送

Every time a segment syncs, Cargo computes a change: how the membership moved. This is what turns a static list into a signal.

bash

undefined

每次Segment同步时，Cargo都会计算变更记录：受众成员的变化情况。这是将静态列表转化为信号的核心。

bash

undefined

What deltas exist for this segment?

该Segment有哪些差值记录？

cargo-ai segmentation change list --segment-uuid <segment-uuid>

→ { "changes": [ { "uuid", "totalRecordsCount", "addedRecordsCount",

"updatedRecordsCount", "removedRecordsCount",

"unchangedRecordsCount", "createdAt" } ] }

Which records actually entered the audience in that delta?

该差值中哪些记录新增到了受众中？

cargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50


`--kinds` is **required** on `change fetch` and takes `added`, `updated`, `removed`, or `unchanged` (comma-separated). Returned rows carry the `_kind`, `_id`, `_title`, and `_time` meta-columns alongside the model's own columns.

`updatedRecordsCount` is always `0` unless the segment was created with `--tracking-column-slugs` — the tracked columns define what "updated" means. Set them at creation time when the segment is meant to feed a monitoring motion.

A segment's most recent delta is also inlined on `segment list` / `segment get` as `lastChange`, so a "what moved?" question rarely needs a second call.

cargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50


`change fetch`必须指定`--kinds`参数，可选值为`added`、`updated`、`removed`或`unchanged`（可逗号分隔多个值）。返回的行数据除了模型自身的列外，还包含`_kind`、`_id`、`_title`和`_time`元列。

除非创建Segment时指定了`--tracking-column-slugs`，否则`updatedRecordsCount`始终为0——跟踪列定义了“更新”的含义。若Segment用于监控场景，请在创建时设置跟踪列。

Segment的最新差值记录也会内嵌在`segment list`/`segment get`的`lastChange`字段中，因此“有哪些变化？”这类问题通常无需额外调用。

What consumes a segment

Segment的使用场景

Segments are an input, not an outcome. Once one exists:

Run something over it — batch a connector action or workflow across every member:
```
../cargo-orchestration/SKILL.md
```
. Batches enroll from a segment; sample 10–20 records and get explicit approval before enrolling the full audience.
Trigger a play on entry — a play whose trigger is a segment fires as records enter it. Play triggers use
```
kind: "filter"
```
and generate their own
```
GENERATED_PLAY_SEGMENT
```
; see
```
../cargo-orchestration/references/examples/plays.md
```
.

Export it —

../cargo-analytics/SKILL.md

(

segment download

needs

--model-uuid

, not

--segment-uuid

— a frequent 400).

Watch it — alert when the audience empties, stalls, or spikes:
```
../cargo-observability/SKILL.md
```
.
Act on it as GTM — signal segments (job change, funding, tech intent) drive the recipes in
```
../cargo-gtm/SKILL.md
```
.
Declare it as code —
```
defineSegment
```
in
```
../cargo-cdk/SKILL.md
```
when the audience should live in git.

Segment是输入，而非输出。创建完成后可用于：

针对受众执行任务——为每个成员批量执行连接器操作或工作流：
```
../cargo-orchestration/SKILL.md
```
。批量任务从Segment获取受众；执行全量任务前，请先抽样10-20条记录并获得明确批准。
进入受众时触发Play——以Segment为触发器的Play会在记录进入受众时触发。Play触发器使用
```
kind: "filter"
```
，并会生成自己的
```
GENERATED_PLAY_SEGMENT
```
；请查看
```
../cargo-orchestration/references/examples/plays.md
```
。
导出受众数据——
```
../cargo-analytics/SKILL.md
```
（
```
segment download
```
需要
```
--model-uuid
```
，而非
```
--segment-uuid
```
——这是常见的400错误原因）。
监控受众——当受众为空、停滞或激增时发送警报：
```
../cargo-observability/SKILL.md
```
。
作为GTM信号——信号类Segment（职位变动、融资、技术意向）驱动
```
../cargo-gtm/SKILL.md
```
中的方案。
以代码声明受众——若受众需存储在git中，请使用
```
../cargo-cdk/SKILL.md
```
中的
```
defineSegment
```
。

Gotchas

常见陷阱

conjonction
, never
conjunction
— silent empty result, no error.
segment download
takes
--model-uuid
, not
--segment-uuid
. The filter travels with the request; the segment UUID is not a valid input there.
change fetch
needs
--uuid
(the change UUID) plus
--kinds
. Passing the segment UUID returns a 400.
change list
needs
--segment-uuid
. Calling it bare returns a 400 complaining that
```
segmentUuid
```
is undefined.
--help
on
change
and
record
subcommands prints the parent help rather than the subcommand's flags (CLI ≥ 1.0.48). Use the Quick reference above; file a report if it still bites.
A segment belongs to exactly one model. Cross-model audiences are a relationship + filter on the joined column, not two segments.
fromPlay: true
segments are owned by a play. Editing one changes what that play targets; removing one breaks it.
--limit
on a segment caps membership, it is not a display page size —
```
--fetching-limit
```
is the page size.

必须使用
conjonction
，而非
conjunction
——拼写错误会导致静默匹配不到任何记录，无报错信息。
segment download
需要
--model-uuid
，而非
--segment-uuid
。筛选器随请求传递，Segment UUID不是有效的输入参数。
change fetch
需要
--uuid
（指变更记录的UUID）和
--kinds
参数。传入Segment UUID会返回400错误。
change list
需要
--segment-uuid
参数。直接调用会返回400错误，提示
```
segmentUuid
```
未定义。
change
和
record
子命令的
--help
会打印父命令的帮助信息，而非子命令的参数说明（CLI ≥ 1.0.48）。请参考上方的快速参考；若问题仍存在，请提交反馈。
一个Segment仅属于一个模型。跨模型受众需通过关联关系+关联列的筛选器实现，而非两个Segment。
fromPlay: true
的Segment属于对应的Play。编辑此类Segment会改变Play的目标受众；删除则会导致Play失效。
Segment的
--limit
参数是限制受众成员数量，而非显示分页大小——
```
--fetching-limit
```
才是分页大小。

When the CLI fails

CLI执行失败时的处理

Two failed attempts on the same command, or behavior that contradicts this skill, goes to the team:

bash

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

同一命令连续两次失败，或行为与本文档描述不符，请提交反馈：

bash

cargo-ai workspaceManagement report create \
  --title "<一行摘要>" \
  --description "<执行的命令、完整errorMessage、预期与实际结果、相关UUID>"