Skip to main content
The Context Builder is a dedicated chat where your team creates and edits the components in your Context Layer — metrics, entities, segments, dimensions, events, parameters, skills, and product memory. You work on your own branch, a private copy of the Context Layer, and nothing you change reaches anyone else until you deploy it. Open it from the Context Builder entry in the sidebar, or from any edit or add action in the Semantic Catalog. Built-in skills — /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:
  1. Build — Create, edit, or delete components in the Builder chat
  2. Test — Check that your changes produce the answers you expect
  3. Audit — Run /audit-changes to catch broken references, duplicates, and gaps
  4. 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.
You can also test from any new Ask Anything chat. While you have an open branch, a Version switch in the chat input lets you choose whether the chat answers from Published or from your Branch. The choice is fixed once the chat starts, so every answer in a conversation comes from the same version.

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.
When there’s a conflict, ClarityQ leaves your branch as it is. The branch banner says “Published has changes that conflict with your branch.” You can keep working. You only need to resolve the conflict before you deploy.

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.
After you save, each decision appears as a card marked Kept Yours, Kept Published, or Merged. The card shows What will be deployed, the version that goes live when you deploy. Use Compare with to see what changed compared to Published or to Your branch. If someone deploys again while you’re resolving, any new conflicts are added to the same chat.

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.
Treat the audit as the equivalent of CI for your Context Layer — run it before every deploy and resolve any findings first.
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.

Deleting and Restoring

Deleting a component is a change on your branch like any other, so it only takes effect when you deploy. To bring back something that was deleted, ask the Builder. It restores the component’s last version as a new change on your branch. The one exception is an event: a deleted event comes back by syncing the raw event again from the Event Catalog with Sync to context layer.

Version History and Rollback

Every version is kept, including changes that went live right away. To see them, click All versions next to the version label. From the list you can view what any version changed, compare it with the current one, or roll back to it. See Context Layer Versioning for the details.