Skip to main content

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.

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