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

# Segments

> Reusable cohort definitions that filter users across any analysis.

A segment is a reusable cohort definition in the Semantic Catalog — a named group of users matching specific criteria. Once defined, a segment can be applied as a filter to any question, metric, or analysis.

Examples: *premium users*, *users who churned in the last 30 days*, *high spenders*, *users from organic acquisition*.

## What a Segment Contains

Each segment has:

* **Name** — A `snake_case` identifier (e.g., `premium_users`, `churned_users`, `high_spenders`)
* **Description** — Who is included in the segment, in business terms (e.g., *"Users with at least one in-app purchase over the date window."*)
* **SQL** — A complete, executable query that returns a distinct list of user identifiers matching the cohort criteria

The SQL must return exactly one column — the user identifier — with distinct values. No extra columns, no metric values, no breakdowns. The segment purely defines *who* is in the group.

## Time Behavior

Like metrics, segments use date parameters in their SQL:

* Most segments use `[DATE_FROM]` and `[DATE_TO]` to scope the cohort to a date window (e.g., *users who made a purchase in the last 30 days*)
* Some segments are timeless (e.g., *users from a specific country*) and don't need date parameters

The agent applies the date parameters based on the user's question and the selected date range.

## How the Agent Uses Segments

When someone asks *"what was revenue for premium users last week?"*, the agent:

1. Finds the **revenue** metric
2. Finds the **premium users** segment
3. Joins the segment's user list with the metric's query as a filter
4. Returns revenue scoped to that cohort

Segments are composable — the agent can combine them with any metric, entity, or dimension without pre-built combinations.

## Building Segments

Segments are created through the [Context Builder](/context-layer/building/how-the-context-layer-builder-works). Type `/segment add` in the Builder chat or describe the cohort you want to define. The agent drafts the SQL, validates that it returns distinct user identifiers, and saves it to your draft.