Segments

Named, filtered views of a model — define them in code with defineSegment and target them from batches, exports, and change feeds.

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.

Next steps

Plays

Trigger automations over the rows a segment tracks.

Querying data

SQL over the models behind your segments.