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 — a named group of users matching specific criteria. The Context Builder is where you create new segments, edit existing ones, and refine their SQL. You can provide a name, description, and SQL, or just describe the cohort you want in plain language. The agent completes whatever is missing, adapts your SQL to ClarityQ standards, validates the result, and saves it to your draft.

​
Starting a Segment

You can start a new segment from three places:
  • Semantic Catalog → Segments — Click Add Segment in the top right. ClarityQ opens a Builder chat with the command pre-filled.
  • Builder chat directly — Type /segment add in any Builder chat.
  • From an Ask Anything conversation — If you’ve been analyzing a user cohort in Ask Anything and want to make it reusable, continue in the Builder. The agent already has the context and can encode the cohort definition into a segment.

​
How the Agent Builds the Segment

Describe the cohort you want — for example, “users who made a purchase in the last 30 days” or “churned users who haven’t logged in for 60 days.” The agent takes it from there:
  1. Checks for duplicates — Searches your existing segments to avoid creating a near-duplicate. If a similar segment already exists, it suggests editing it instead.
  2. Identifies the source — Finds the right tables and user identifier column in your data, and confirms with you.
  3. Determines time behavior — Figures out whether the segment should scope to a date range (e.g., users active in the last 28 days), a single point in time (e.g., subscribers as of March 1), or be timeless (e.g., users who ever verified their email). If the wording is ambiguous, the agent asks a clarifying question.
  4. Writes and validates — Generates the SQL, validates that it returns a distinct list of user identifiers, and saves the segment to your draft.
The SQL must return exactly one column — the user identifier — with distinct values. No extra columns, no metric values, no breakdowns. The agent enforces this automatically.

​
Editing and Deleting Segments

From the Segments tab of the Semantic Catalog:
  • Edit — Open the segment and click Edit in the row menu, or type /segment edit <segment_name> in a Builder chat. The agent loads the current definition and walks you through the changes.
  • Delete — Choose Delete from the row menu, or type /segment delete <segment_name>. Deletion removes the segment from the catalog once your draft is deployed.

​
Adding Several Segments at Once

Like metrics, you can create multiple segments in one go:
  • List them in the chat — Ask the agent to add several segments in one message (“add segments for high spenders, churned users, and new signups”). The agent shows a proposal with each segment’s name, description, and cohort criteria, and waits for your confirmation.
  • Attach a file — Drop a simple .xlsx spreadsheet (single tab) or a .csv file with your definitions into the Builder message. The agent reads the file, confirms what it understood, and creates the segments in bulk.
When uploading a file, include only segments — don’t mix segments with other component types. This keeps the agent focused and reduces the chance of errors.

​
After Creating

A newly created segment lands in your draft and is only available to you until you deploy. To make a segment live for everyone:
  1. Test in Chat to verify the segment works as expected — for example, ask “how many high spenders were there last month?” and confirm the count makes sense.
  2. Run the audit (/audit-changes) on your draft to catch any issues before deploying.
  3. Deploy the draft from the orange banner at the top of the screen. The segment becomes part of the published catalog and available to everyone in your organization.