> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/models/overview): 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

```ts segments/us-icp.ts theme={null}
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](/plays/triggering#eligibility-filter) 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).                                                                                                           |

<Note>
  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.
</Note>

To reference a segment that already exists in the workspace instead of defining it, use `segmentRef("<segment-uuid>")` — see [Referencing existing resources](/deploy/deploying#referencing-existing-resources).

## Use a segment

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

```bash theme={null}
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
```

<Warning>
  `segment fetch` and `segment download` take `--model-uuid`, not
  `--segment-uuid` — they query a model with segment-style filters.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Plays" icon="play" href="/plays/triggering">
    Trigger automations over the rows a segment tracks.
  </Card>

  <Card title="Querying data" icon="database" href="/models/querying">
    SQL over the models behind your segments.
  </Card>
</CardGroup>