/metric, /entity, /segment, /dimension, /event, /parameter, /skill, and /product-memory — let you build and maintain every kind of component.
Building requires write access to the Context Layer — Admins and Analyst Contributors by default. See User Management and Roles for the full breakdown.
Your Branch
Click Start Editing in the Builder and ClarityQ creates your branch from the current published version. From then on, every change you make lands on your branch. Nothing is locked. Other editors each work on their own branch at the same time, and everyone else keeps using the published version as normal. You can also run several Builder chats on your branch at once. While your branch is open, a banner across the top of ClarityQ reads “You are editing” followed by your branch, with how many changes it holds. Click the change count to compare your branch with the published version.The Build Cycle
Every set of changes follows the same cycle:- Build — Create, edit, or delete components in the Builder chat
- Test — Check that your changes produce the answers you expect
- Audit — Run
/audit-changesto catch broken references, duplicates, and gaps - Deploy — Make your branch the live version for everyone
You can also arrive at the Builder from a Diagnosis: when you thumbs-down an answer in Ask Anything and click Fix now, the Builder opens with the suggested fix pre-loaded, ready to review and build.
The Branch Banner
The banner gives you everything you need while your branch is open:- New Build — Start another Builder chat on your branch.
- Test in Chat — Open an Ask Anything chat that answers from your branch instead of the published version. Ask the questions your changes are meant to answer — for example, after redefining your DAU metric, ask “what was DAU last week?” — and check the agent picks up your new definition.
- Discard — Permanently throw away your branch and all its changes. There’s no undo.
- Deploy — Make your branch the live version for everyone.
When Changes Conflict
Several people can work at the same time, each on their own branch. So someone else may deploy while you’re still working.How Your Branch Stays Up to Date
Each time someone deploys, ClarityQ brings the new published changes into your branch for you. If their changes don’t touch what you changed, this happens quietly and you don’t need to do anything.What Counts as a Conflict
A conflict happens when your branch and the published version changed the same item in ways that can’t be combined. For example:- You both changed the same part of an item, such as its SQL or its description.
- You both set the same field to different values.
- One side deleted an item and the other side changed it.
Resolving Conflicts
1
Click Deploy
The Resolve conflicts with Published dialog lists each item in conflict. Click Resolve in Builder.
2
Work through the resolution chat
A new Builder chat opens. A bar at the top says “This chat is resolving the conflicts between your branch and Published.”The Builder first shows what bringing in the published changes will do: what’s all set, and what needs your decision. Then it goes through each conflict one at a time. For each one, it shows both versions in full, explains why they conflict, and asks you what to keep. You can keep your version, keep the published version, or combine the two.
3
Save the result
When everything is decided, the Builder asks “Save the conflict resolution to your branch?” Nothing reaches your branch until you approve.
4
Deploy
Once the conflicts are resolved, the resolution chat closes and you can deploy as normal.
While You’re Resolving
Until the conflicts are resolved:- Deploy is turned off. The banner says “Finish resolving conflicts to enable deployment” and shows Open resolution chat, so you can go back to it from anywhere.
- Your other Builder chats on the branch can’t save changes. They show “Changes in this chat are disabled until conflicts are resolved.”
- Changes made from the catalog pages, such as Approve, Delete, or Sync to context layer, are blocked with “Finish resolving conflicts first.”
- The resolution chat can’t be deleted.
- On the Versions page, your branch shows as Resolving conflicts in the open branches list.
Stopping Partway
Click Stop resolving in the resolution chat’s bar to leave. Anything the chat resolved but didn’t save yet is dropped. The chat becomes read-only, and the next time you click Deploy, a new resolution chat starts on the conflicts that are left. Discarding your branch also ends the resolution.Deploying
When you press Deploy, a dialog shows your branch, a summary of what it changes, and the full list of changes. If your branch hasn’t been audited since its last change, ClarityQ asks you to Run Audit first, or to Deploy Without Audit. The audit (/audit-changes) looks at what your branch changes — broken references, dead tables, duplicate definitions, orphaned components, and similar gaps — and catches mistakes before they reach everyone.
If your branch deleted events or parameters, the dialog also offers to hide the matching raw events and parameters in the Event Catalog, so the two stay in step.
Deploying publishes your branch as a new version, and the change is recorded in the version history.