How Versions Work
The Context Layer always has one published version — the version everyone uses and that the agent answers from. When you click Start Editing in the Builder, ClarityQ creates your branch: a private copy of the published version. Your changes are saved to your branch until you deploy, and nothing is locked for anyone else. Each editor has their own branch, so several people can work at the same time. Deploying makes your branch the new published version. The previous version isn’t lost — it stays in the version history permanently.When Someone Else Deploys First
Each time someone deploys, ClarityQ brings the new published changes into every open branch. If those changes don’t overlap with yours, this happens without you doing anything. If you and someone else changed the same item in ways that can’t be combined, that’s a conflict. Your branch is left as it is, and you resolve the conflict in a Builder chat before you deploy. See When Changes Conflict for the full steps.What Gets Versioned
These components are versioned. Most changes to them are made on a branch and go live when you deploy:- Entities and their dimensions
- Events and their parameters
- Metrics
- Segments
- Skills
- Product memory entries
Changes That Go Live Right Away
A few quick actions skip the branch. They go straight to the published version, so everyone sees them at once. Each one is saved as its own small version, credited to the person who made it:- Approve — from a Semantic Catalog page or the Inbox.
- Editing a description — directly on a Semantic Catalog page.
- Fetch all values — on an event parameter.
- Values the agent finds while answering questions.
- An event’s SQL being regenerated.
- New parameters joining an event when they’re approved in the Event Catalog.
If someone else changed an item after you opened it, your action is refused with “This item changed since you opened it. Reload to see the latest and redo your change.” Reload the page and try again.
What’s Not Versioned
Some parts of ClarityQ live outside branches and take effect as soon as they change:- Table Catalog — Tables and columns are discovered directly from your data warehouse and kept current by daily discovery jobs.
- Event Catalog — Raw events and parameters come from your tracking. Syncing a raw event creates an event in the Semantic Catalog; from then on, that event is versioned like any other component.
- Files — Files take effect as soon as you upload or change them.
- Personal memory — Saved and applied right away in your own conversations.
The Change Set
Every version includes an auto-generated description of what changed. The change set records every component that was:- Created — New components added in this version
- Modified — Existing components that were updated
- Deleted — Components that were removed
Version History
To see the version history, click All versions next to the version label. The page lists every deploy and rollback with its version number, summary, who created it, and when it was deployed. Changes that go live right away are smaller versions. They’re listed under the deploy they followed: expand a deploy’s row to see them, each with its own summary, author, and Published On date. A deploy or rollback starts a new version number, such as v3.0.0. Each change after that raises the last number: v3.0.1, v3.0.2, and so on, until the next deploy.Actions on Each Version
- View Changes — See every component created, modified, or deleted in that version. Available on every version.
- Compare to Current — See the cumulative changes between that version and the current published version. Available on any version that isn’t the current one.
- Rollback — Restore the Context Layer to that version and publish it as a new version, right away. ClarityQ shows you the changes that will be undone before you confirm. Available to anyone who can edit the Context Layer, on any version that isn’t the current one.
Open Branches
The same page lists the branches currently open, with each branch’s owner, how many changes it holds, its state — Open, or Resolving conflicts while its owner is resolving a conflict — and when it was last active. Admins can delete a branch from this list, for example one left behind by someone who has moved on. Deleting a branch discards its changes.Common Scenarios
”What changed in the last deploy?”
Open the version history and click View Changes on the latest version. You’ll see exactly what was created, modified, or deleted.”Something broke — what changed since the last known good version?”
Find the version you trust and click Compare to Current. This shows every change between that version and what’s live now.”I need to undo a bad deploy”
Find the version you want to go back to and click Rollback. The Context Layer is restored to that version straight away and published as a new version. The bad version stays in the history — nothing is lost.”I deleted something by mistake”
If it was only deleted on your branch, ask the Builder to bring it back. If the deletion was already deployed, you can still ask the Builder — it restores the component’s last version as a new change on your branch, which you then deploy. A deleted event is the exception: bring it back by syncing the raw event again from the Event Catalog.Rollback publishes a new version on top of the current one. It doesn’t delete or rewrite history.