How to create and edit reusable user cohort definitions through the Context Builder.
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 branch.
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:
Checks for duplicates — Searches your existing segments to avoid creating a near-duplicate. If a similar segment already exists, it suggests editing it instead.
Identifies the source — Finds the right tables and user identifier column in your data, and confirms with you.
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.
Writes and validates — Generates the SQL, validates that it returns a distinct list of user identifiers, and saves the segment to your branch.
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 branch 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 on your branch and is only available to you until you deploy. To make a segment live for everyone:
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.
Run the audit (/audit-changes) on your branch to catch any issues before deploying.
Deploy your branch from the banner at the top of the screen. The segment becomes part of the published catalog and available to everyone in your organization.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"ClarityQ Documentation","colors":{"primary":"#5A57FC","light":"#9391ff","dark":"#5A57FC"},"logo":{"light":"https://mintcdn.com/clarityq/RMDLvxRyN9-VIA7h/logo/light.svg?fit=max\u0026auto=format\u0026n=RMDLvxRyN9-VIA7h\u0026q=85\u0026s=f8d4e57d3c0e50c3f720e5b6a7afef0b","dark":"https://mintcdn.com/clarityq/RMDLvxRyN9-VIA7h/logo/dark.svg?fit=max\u0026auto=format\u0026n=RMDLvxRyN9-VIA7h\u0026q=85\u0026s=f838d08af4bdbf4b9f80be89bbd57203"},"favicon":"https://mintcdn.com/clarityq/RMDLvxRyN9-VIA7h/favicon.svg?fit=max\u0026auto=format\u0026n=RMDLvxRyN9-VIA7h\u0026q=85\u0026s=ccd0c18ac98544dea1c3e42018f2db76","navbar":{"links":[{"href":"mailto:support@clarityq.ai","label":"Support"}]},"footer":{"socials":{"linkedin":"https://linkedin.com/company/clarityq"}},"seo":{"metatags":{"msvalidate.01":"2653DA8E28F50109EA5130713FEE874C"},"indexing":"all"},"contextual":{"options":["copy","view","chatgpt","claude","perplexity","mcp","cursor","vscode"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"clarityq","hasAudioNarration":false,"actualSubdomain":"clarityq","customDomains":["docs.clarityq.ai"],"gitSource":{"type":"github","owner":"clarityq","repo":"clarityq-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{},"buildId":"6afd9ba25e3b11ff7dbe3e94","clientVersion":"0.0.4177","searchFilterCounts":[{"language":"default","tag":"Context Layer","count":19},{"language":"default","tag":"Data Warehouse Connections","count":11},{"language":"default","tag":"Integrations","count":11},{"language":"default","tag":"Building the Context Layer","count":10},{"language":"default","tag":"API Reference","count":8},{"language":"default","tag":"Ask Anything","count":8},{"language":"default","tag":"Administration","count":7},{"language":"default","tag":"Semantic Catalog","count":6},{"language":"default","tag":"Event Catalog","count":5},{"language":"default","tag":"Dashboards","count":5}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"context-layer/building/building-segments","slug":"/context-layer/building/building-segments","pageMetadata":{"title":"Building Segments","description":"How to create and edit reusable user cohort definitions through the Context Builder.","href":"/context-layer/building/building-segments"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"How to create and edit reusable user cohort definitions through the Context Builder.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,em:`em`,li:`li`,ol:`ol`,p:`p`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{Heading,Tip}=_components;if(!Heading)_missingMdxReference(`Heading`,true);if(!Tip)_missingMdxReference(`Tip`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`A `,_jsx(_components.a,{href:`/context-layer/semantic-catalog/segments`,children:`segment`}),` is a reusable cohort definition — a named group of users matching specific criteria. The `,_jsx(_components.strong,{children:`Context Builder`}),` is where you create new segments, edit existing ones, and refine their SQL.`]}),`\n`,_jsx(_components.p,{children:`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 branch.`}),`\n`,_jsx(Heading,{level:`2`,id:`starting-a-segment`,children:`Starting a Segment`}),`\n`,_jsx(_components.p,{children:`You can start a new segment from three places:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Semantic Catalog → Segments`}),` — Click `,_jsx(_components.strong,{children:`Add Segment`}),` in the top right. ClarityQ opens a Builder chat with the command pre-filled.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Builder chat directly`}),` — Type `,_jsx(_components.code,{children:`/segment add`}),` in any Builder chat.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`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.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`how-the-agent-builds-the-segment`,children:`How the Agent Builds the Segment`}),`\n`,_jsx(_components.p,{children:`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:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Checks for duplicates`}),` — Searches your existing segments to avoid creating a near-duplicate. If a similar segment already exists, it suggests editing it instead.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Identifies the source`}),` — Finds the right tables and user identifier column in your data, and confirms with you.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Determines time behavior`}),` — Figures out whether the segment should scope to a date range (e.g., `,_jsx(_components.em,{children:`users active in the last 28 days`}),`), a single point in time (e.g., `,_jsx(_components.em,{children:`subscribers as of March 1`}),`), or be timeless (e.g., `,_jsx(_components.em,{children:`users who ever verified their email`}),`). If the wording is ambiguous, the agent asks a clarifying question.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Writes and validates`}),` — Generates the SQL, validates that it returns a distinct list of user identifiers, and saves the segment to your branch.`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`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.`}),`\n`,_jsx(Heading,{level:`2`,id:`editing-and-deleting-segments`,children:`Editing and Deleting Segments`}),`\n`,_jsxs(_components.p,{children:[`From the `,_jsx(_components.strong,{children:`Segments`}),` tab of the Semantic Catalog:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Edit`}),` — Open the segment and click `,_jsx(_components.strong,{children:`Edit`}),` in the row menu, or type `,_jsx(_components.code,{children:`/segment edit \u003csegment_name>`}),` in a Builder chat. The agent loads the current definition and walks you through the changes.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Delete`}),` — Choose `,_jsx(_components.strong,{children:`Delete`}),` from the row menu, or type `,_jsx(_components.code,{children:`/segment delete \u003csegment_name>`}),`. Deletion removes the segment from the catalog once your branch is deployed.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`adding-several-segments-at-once`,children:`Adding Several Segments at Once`}),`\n`,_jsx(_components.p,{children:`Like metrics, you can create multiple segments in one go:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`List them in the chat`}),` — Ask the agent to add several segments in one message (`,_jsx(_components.em,{children:`“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.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Attach a file`}),` — Drop a simple `,_jsx(_components.code,{children:`.xlsx`}),` spreadsheet (single tab) or a `,_jsx(_components.code,{children:`.csv`}),` file with your definitions into the Builder message. The agent reads the file, confirms what it understood, and creates the segments in bulk.`]}),`\n`]}),`\n`,_jsx(Tip,{children:_jsx(_components.p,{children:`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.`})}),`\n`,_jsx(Heading,{level:`2`,id:`after-creating`,children:`After Creating`}),`\n`,_jsx(_components.p,{children:`A newly created segment lands on your branch and is only available to you until you deploy. To make a segment live for everyone:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Test in Chat`}),` to verify the segment works as expected — for example, ask `,_jsx(_components.em,{children:`“how many high spenders were there last month?”`}),` and confirm the count makes sense.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Run the audit`}),` (`,_jsx(_components.code,{children:`/audit-changes`}),`) on your branch to catch any issues before deploying.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Deploy`}),` your branch from the banner at the top of the screen. The segment becomes part of the published catalog and available to everyone in your organization.`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Building Segments","description":"How to create and edit reusable user cohort definitions through the Context Builder.","href":"/context-layer/building/building-segments"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Starting a Segment","slug":"starting-a-segment","depth":2,"children":[]},{"title":"How the Agent Builds the Segment","slug":"how-the-agent-builds-the-segment","depth":2,"children":[]},{"title":"Editing and Deleting Segments","slug":"editing-and-deleting-segments","depth":2,"children":[]},{"title":"Adding Several Segments at Once","slug":"adding-several-segments-at-once","depth":2,"children":[]},{"title":"After Creating","slug":"after-creating","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"clarityq","siteName":"ClarityQ Documentation","title":"Building Segments - ClarityQ Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-15T11:29:18.507Z","originalFileLocation":"context-layer/building/building-segments.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"How to create and edit reusable user cohort definitions through the Context Builder.\">\u003cmeta data-mint-head name=\"application-name\" content=\"ClarityQ Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Building Segments - ClarityQ Documentation\">\u003cmeta data-mint-head property=\"og:description\" content=\"How to create and edit reusable user cohort definitions through the Context Builder.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"ClarityQ Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.clarityq.ai/context-layer/building/building-segments\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://clarityq.mintlify.site/_mintlify/api/og/v2?division=Building+the+Context+Layer\u0026amp;title=Building+Segments\u0026amp;description=How+to+create+and+edit+reusable+user+cohort+definitions+through+the+Context+Builder.\u0026amp;theme=8a1189787dd42c7f361220a1\u0026amp;signature=8b74073a0da625e86e0f2af8d9e6d3194600b1ec304d590cb3af1fa7a1b40df3\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Building Segments - ClarityQ Documentation\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"How to create and edit reusable user cohort definitions through the Context Builder.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://clarityq.mintlify.site/_mintlify/api/og/v2?division=Building+the+Context+Layer\u0026amp;title=Building+Segments\u0026amp;description=How+to+create+and+edit+reusable+user+cohort+definitions+through+the+Context+Builder.\u0026amp;theme=8a1189787dd42c7f361220a1\u0026amp;signature=8b74073a0da625e86e0f2af8d9e6d3194600b1ec304d590cb3af1fa7a1b40df3\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/clarityq/YW4hrpKdd3h3lviU/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"ClarityQ Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#5A57FC\">\u003cmeta data-mint-head name=\"msvalidate.01\" content=\"2653DA8E28F50109EA5130713FEE874C\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.clarityq.ai/context-layer/building/building-segments\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/context-layer/building/building-segments.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.clarityq.ai/#organization\",\"name\":\"ClarityQ Documentation\",\"url\":\"https://docs.clarityq.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/clarityq/RMDLvxRyN9-VIA7h/logo/light.svg?fit=max\u0026auto=format\u0026n=RMDLvxRyN9-VIA7h\u0026q=85\u0026s=f8d4e57d3c0e50c3f720e5b6a7afef0b\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.clarityq.ai#website\",\"name\":\"ClarityQ Documentation\",\"url\":\"https://docs.clarityq.ai\",\"publisher\":{\"@id\":\"https://docs.clarityq.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.clarityq.ai/context-layer/building/building-segments#webpage\",\"url\":\"https://docs.clarityq.ai/context-layer/building/building-segments\",\"name\":\"Building Segments\",\"description\":\"How to create and edit reusable user cohort definitions through the Context Builder.\",\"dateModified\":\"2026-11-15T11:29:18.507Z\",\"isPartOf\":{\"@id\":\"https://docs.clarityq.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.clarityq.ai/context-layer/building/building-segments#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.clarityq.ai/context-layer/building/building-segments#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Building the Context Layer\",\"item\":\"https://docs.clarityq.ai/context-layer/building/recommended-build-order\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Building Segments\",\"item\":\"https://docs.clarityq.ai/context-layer/building/building-segments\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.clarityq.ai/context-layer/building/building-segments#article\",\"headline\":\"Building Segments\",\"name\":\"Building Segments\",\"description\":\"How to create and edit reusable user cohort definitions through the Context Builder.\",\"url\":\"https://docs.clarityq.ai/context-layer/building/building-segments\",\"mainEntityOfPage\":{\"@id\":\"https://docs.clarityq.ai/context-layer/building/building-segments#webpage\"},\"dateModified\":\"2026-11-15T11:29:18.507Z\",\"publisher\":{\"@id\":\"https://docs.clarityq.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.clarityq.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"ClarityQ Documentation\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"ClarityQ Documentation\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/context-layer/building/building-segments.md","siteName":"ClarityQ Documentation","nav":{"global":null,"groups":[{"group":"Get Started","pages":[{"title":"What is ClarityQ?","href":"/get-started/what-is-clarityq"},{"title":"Connect Your Data Warehouse","href":"/get-started/connect-your-data-warehouse"},{"title":"Build Your Context Layer","href":"/get-started/build-your-context-layer"},{"title":"Your First Chat","href":"/get-started/your-first-chat"},{"title":"Best Practices","href":"/get-started/best-practices"}]},{"group":"Data Warehouse Connections","pages":[{"title":"BigQuery","href":"/data-warehouse/bigquery"},{"title":"Snowflake","href":"/data-warehouse/snowflake"},{"title":"Amazon Athena","href":"/data-warehouse/athena"},{"title":"Amazon Redshift","href":"/data-warehouse/redshift"},{"title":"PostgreSQL","href":"/data-warehouse/postgres"},{"title":"Databricks","href":"/data-warehouse/databricks"},{"title":"MaxCompute","href":"/data-warehouse/maxcompute"},{"title":"Trino","href":"/data-warehouse/trino"},{"title":"ClickHouse","href":"/data-warehouse/clickhouse"},{"title":"Azure SQL","href":"/data-warehouse/sqlserver"},{"title":"Signing In With Your Own Warehouse Account","sidebarTitle":"Signing In With Your Own Account","href":"/data-warehouse/signing-in-with-your-own-account"}]},{"group":"Context Layer","pages":[{"title":"What is the Context Layer?","href":"/context-layer/what-is-the-context-layer"},{"group":"Table Catalog","pages":[{"title":"What is the Table Catalog?","href":"/context-layer/table-catalog/what-is-the-table-catalog"},{"title":"Setting Up Your Table Catalog","href":"/context-layer/table-catalog/setting-up-your-table-catalog"},{"title":"Daily Discovery Jobs","href":"/context-layer/table-catalog/daily-discovery-jobs"}]},{"group":"Event Catalog","pages":[{"title":"What is the Event Catalog?","href":"/context-layer/event-catalog/what-is-the-event-catalog"},{"title":"Setting Up Your Event Catalog","href":"/context-layer/event-catalog/setting-up-your-event-catalog"},{"title":"Daily Discovery Jobs","href":"/context-layer/event-catalog/daily-discovery-jobs"},{"title":"Missing Description Wizard","href":"/context-layer/event-catalog/missing-description-wizard"},{"title":"Syncing Events to the Semantic Catalog","href":"/context-layer/event-catalog/syncing-events-to-the-semantic-catalog"}]},{"group":"Semantic Catalog","pages":[{"title":"What is the Semantic Catalog?","href":"/context-layer/semantic-catalog/what-is-the-semantic-catalog"},{"title":"Entities","href":"/context-layer/semantic-catalog/entities"},{"title":"Dimensions","href":"/context-layer/semantic-catalog/dimensions"},{"title":"Metrics","href":"/context-layer/semantic-catalog/metrics"},{"title":"Segments","href":"/context-layer/semantic-catalog/segments"},{"title":"Events","href":"/context-layer/semantic-catalog/events"}]},{"title":"Skills","href":"/context-layer/skills"},{"title":"Rules","href":"/context-layer/rules"},{"title":"Memory","href":"/context-layer/memory"},{"title":"Files","href":"/context-layer/files"}]},{"group":"Building the Context Layer","pages":[{"title":"Recommended Build Order","href":"/context-layer/building/recommended-build-order"},{"title":"How the Context Layer Builder works","href":"/context-layer/building/how-the-context-layer-builder-works"},{"title":"Building Entities from Tables","href":"/context-layer/building/building-entities-from-tables"},{"title":"Building Metrics","description":"How to create, edit, and ship metrics through the Context Builder.","href":"/context-layer/building/building-metrics"},{"title":"Building Segments","href":"/context-layer/building/building-segments"},{"title":"Building Skills","description":"How to create and edit custom skills through the Context Builder.","href":"/context-layer/building/building-skills"},{"title":"Building Product Memory","href":"/context-layer/building/building-memory"},{"title":"Context Layer Versioning","href":"/context-layer/building/context-layer-versioning"},{"title":"Inbox","href":"/context-layer/building/inbox"},{"title":"Building Events from the Event Catalog","href":"/context-layer/building/building-events-from-the-event-catalog"}]},{"group":"Ask Anything","pages":[{"title":"How Ask Anything Works","href":"/ask-anything/how-ask-anything-works"},{"title":"Asking Questions","href":"/ask-anything/asking-questions"},{"title":"Understanding Responses","href":"/ask-anything/understanding-responses"},{"title":"Diagnosing Answers","href":"/ask-anything/diagnosing-answers"},{"title":"Context Coverage","href":"/ask-anything/context-coverage"},{"title":"Sharing \u0026 Collaboration","href":"/ask-anything/sharing-and-collaboration"},{"title":"Unified Workspaces","href":"/ask-anything/unified-workspaces"},{"title":"Errors \u0026 Troubleshooting","href":"/ask-anything/errors-and-troubleshooting"}]},{"group":"Dashboards","pages":[{"title":"What are Dashboards?","href":"/dashboards/what-are-dashboards"},{"title":"Creating and Editing Dashboards","href":"/dashboards/creating-and-editing-dashboards"},{"title":"Asking About a Dashboard's Data","href":"/dashboards/asking-about-dashboard-data"},{"title":"Scheduling Dashboards","href":"/dashboards/scheduling-dashboards"},{"title":"Sharing and Managing Dashboards","href":"/dashboards/sharing-and-managing-dashboards"}]},{"group":"Automations","pages":[{"title":"What are Tasks?","href":"/automations/what-are-tasks"},{"title":"Creating \u0026 Scheduling Tasks","href":"/automations/creating-and-scheduling-tasks"},{"title":"Task Delivery \u0026 Notifications","href":"/automations/task-delivery-and-notifications"}]},{"group":"Integrations","pages":[{"group":"Embed","pages":[{"title":"Embedding ClarityQ","href":"/integrations/embed/embedding-clarityq"},{"openapi":"post /api/v1/products/{product_id}/embed/token","title":"Mint an embed token","href":"/integrations/embed/mint-embed-token"},{"openapi":"post /api/v1/products/{product_id}/conversations","title":"List conversations","href":"/integrations/embed/list-conversations"}]},{"group":"Slack","pages":[{"title":"Connecting Slack","href":"/integrations/slack/connecting-slack"},{"title":"Using ClarityQ in Slack","href":"/integrations/slack/using-clarityq-in-slack"}]},{"group":"MCP Connectors","pages":[{"title":"MCP Connectors","href":"/integrations/mcp/connecting-mcp-servers"},{"title":"Using Apps","href":"/integrations/mcp/using-mcp-servers"},{"title":"Connecting Atlassian (Jira)","href":"/integrations/mcp/connecting-atlassian"},{"title":"Connecting GitHub","href":"/integrations/mcp/connecting-github"}]},{"group":"ClarityQ MCP Server","pages":[{"title":"Connecting AI Assistants","href":"/integrations/clarityq-mcp-server/connecting-ai-assistants"},{"title":"Using ClarityQ from AI Assistants","href":"/integrations/clarityq-mcp-server/using-clarityq-from-ai-assistants"}]}]},{"group":"Administration","pages":[{"title":"Context Hub","href":"/admin/context-hub"},{"title":"User Management and Roles","href":"/admin/user-management-and-roles"},{"title":"Organization Settings","href":"/admin/organization-settings"},{"title":"Filters","href":"/admin/filters"},{"title":"Usage Dashboard","href":"/admin/usage-dashboard"},{"title":"Usage Limits and Top-Ups","href":"/admin/usage-limits-and-top-ups"},{"title":"Security and Compliance","href":"/admin/security-and-compliance"}]},{"group":"API Reference","pages":[{"title":"API Reference","href":"/api-reference/index"},{"openapi":"post /api/v1/products/{product_id}/ask","title":"Ask a question","href":"/api-reference/api/ask-a-question"},{"openapi":"get /api/v1/products/{product_id}/conversations/{conversation_id}/status","title":"Get conversation status","href":"/api-reference/api/get-conversation-status"},{"openapi":"get /api/v1/products/{product_id}/conversations/{conversation_id}/summary","title":"Get conversation summary","href":"/api-reference/api/get-conversation-summary"},{"title":"Submit Feedback","openapi":"put /api/v1/products/{product_id}/conversations/{conversation_id}/feedback","href":"/api-reference/api/submit-feedback"},{"openapi":"get /api/v1/products/{product_id}/tasks/{task_id}/last-run-summary","title":"Get last completed task run summary","href":"/api-reference/api/get-last-completed-task-run-summary"},{"title":"Get Prompt Usage","openapi":"get /api/v1/products/{product_id}/usage/prompts","href":"/api-reference/api/get-prompt-usage"},{"title":"Submit External Feedback","openapi":"post /api/v1/products/{product_id}/external-feedback","href":"/api-reference/api/submit-external-feedback"}]},{"group":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]}]},"basePath":"","title":"Building Segments - ClarityQ Documentation","deploymentId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","buildId":"dpl_HhUetB7eHHDAmK9T1Teip38TgFx9","dynamics":[],"chunks":[]}