Skip to main content
An event is a tracked user action — signup_completed, purchase_made, level_finished — brought into the Semantic Catalog so the agent can use it to answer questions. Each event comes with its parameters, the properties recorded with it, which you can filter and group by.

Raw Events and Events

ClarityQ keeps two related things, and the difference matters:
  • Raw events live in the Event Catalog. They’re your tracking exactly as it arrives — every event your product sends, with its parameters and user properties, quirks and all.
  • Events live in the Semantic Catalog. They’re the modeled, clean version the agent actually queries: implementation errors corrected, noise stripped out, and descriptions and rules that explain what the event means and how to use it.
The agent doesn’t query the Event Catalog directly. It works from the Semantic Catalog, so an event only becomes usable once its raw event has been synced.

What an Event Contains

Each event has:
  • Name — Derived from the raw event’s name
  • Description — What the event means and when it fires
  • Parameters — The event’s properties and user properties, each usable for filtering and grouping
  • Rules — Optional instructions the agent must follow whenever it uses this event (see Rules)

How Events Are Created

Events aren’t built in the Context Builder. They come from the Event Catalog:
  1. Find the raw event in the Event Catalog.
  2. Select it and choose Sync to context layer.
  3. ClarityQ creates the event and its parameters on your branch. They go live for everyone when you deploy.
A raw event whose description is still pending becomes a Pending event, which the agent can already use — you approve it later. See Syncing Events to the Semantic Catalog for the details.

Changing an Event

Once an event exists, you change it in the Context Builder, like any other component. Two skills cover it:
  • /event — Change an event and its parameters: descriptions (one at a time or in batch), rules, and deletions.
  • /parameter — Build and fix parameters. Add a custom parameter when a value is worked out from the event’s own row — a CASE or IF over its columns, for example.
You don’t edit an event’s SQL. How the event is fetched is ClarityQ’s job; how to use it is yours, and that’s what rules are for.
A value that has to be looked up in another table isn’t a parameter. Keep the key the event already carries — a user ID, say — and add a rule to it saying which table to look the value up in.
Changes to events are versioned like the rest of the Context Layer: they’re made on your branch and go live when you deploy. See Context Layer Versioning.

How the Agent Uses Events

When someone asks about behavior — “how many users completed signup last week?” or “what are the top events by volume?” — the agent finds the relevant event and uses it to build the query. Its parameters allow breakdowns like “signups by platform” or “purchases filtered to premium plan”.

Rules on Events

An event can carry Rules — named instructions the agent must follow whenever it uses that event. So can each of its parameters: a rule on the event applies whenever the event is used, while a rule on a parameter applies to that property. For example, on a purchase_made event: Exclude sandbox purchases — “Test-store transactions are present in the data before March 2026. Filter them out for any date range reaching back that far.” And on that event’s price parameter: Price is in cents — “Values are stored in cents. Divide by 100 before presenting an amount.” Add and change these rules in the Builder with /event or /parameter.

Staying in Step with the Event Catalog

An event and its raw event stay linked. New parameters join the event as you approve them in the Event Catalog, and changing a description on either side updates the other, so they always match. Deleting an event is a change on your branch. When you deploy it, ClarityQ asks whether to also hide the matching raw event in the Event Catalog. To bring a deleted event back, sync its raw event again.