Segments

A segment is a named, filtered view of a model: the records matching a filter, optionally sorted, limited, and scoped to specific columns. Segments are what you point batches, exports, and change feeds at. You define one with defineSegment.

Define a segment

segments/us-icp.ts

import { defineSegment } from "@cargo-ai/cdk";
import { contacts } from "../models/contacts";

export const usIcp = defineSegment("us-icp", {
  model: contacts,
  filter: {
    conjonction: "and",
    groups: [{
      conjonction: "and",
      conditions: [
        { kind: "string", columnSlug: "country", operator: "is", values: ["US"] },
        { kind: "number", columnSlug: "employee_count", operator: "greaterThan", values: [50] },
      ],
    }],
  },
  sort: [{ columnSlug: "employee_count", kind: "desc" }],
  limit: 1000,
});

Field	Role
`model`	The model this segment filters — a model handle or `modelRef(uuid)`. Fixed at create; changing it means a new segment.
`filter`	Which records the segment includes — the same JSON shape as play eligibility filters and the UI segment builder.
`sort` / `limit`	Optional ordering and cap on the view.
`trackingColumnSlugs`	Columns whose changes feed the segment’s change feed.
`columnSlugs`	Columns the segment exposes (defaults to all).

The server derives the segment’s own slug from its name (which defaults to the title-cased code slug), and the segment is state-tracked and adopted by name — so re-deploying the same definition reattaches rather than duplicates.

To reference a segment that already exists in the workspace instead of defining it, use segmentRef("<segment-uuid>") — see Referencing existing resources.

Use a segment

Run a play across a segment as a batch, or export its records:

cargo-ai segmentation segment list                    # → segmentUuid
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"segment","segmentUuid":"<uuid>"}' \
  --wait-until-finished

cargo-ai segmentation segment fetch --model-uuid <model-uuid>      # records as JSON
cargo-ai segmentation segment download --model-uuid <model-uuid>   # records as a file

segment fetch and segment download take --model-uuid, not --segment-uuid — they query a model with segment-style filters.

Define a segment

Use a segment

Next steps

Plays

Querying data

​Define a segment

​Use a segment

​Next steps

Plays

Querying data

Define a segment

Use a segment

Next steps