> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Events from the Event Catalog

> How raw events from the Event Catalog become events and parameters in the Semantic Catalog, and how you change them afterwards in the Context Builder.

[Events](https://docs.clarityq.ai/context-layer/semantic-catalog/events.md) are the Semantic Catalog components that represent tracked user actions — `signup_completed`, `purchase_made`, `level_finished`. You don't build them from scratch in the Context Builder. You create them by syncing **raw events** from the [Event Catalog](https://docs.clarityq.ai/context-layer/event-catalog/what-is-the-event-catalog.md), and then refine them in the Builder.

## How Events Are Created

**1. Approve the raw event in the Event Catalog**

Give the raw event a description, and approve its parameters and user properties. The [Missing Description Wizard](https://docs.clarityq.ai/context-layer/event-catalog/missing-description-wizard.md) speeds this up.

**2. Sync it**

Select one or more raw events and choose **Sync to context layer**. See [Syncing Events to the Semantic Catalog](https://docs.clarityq.ai/context-layer/event-catalog/syncing-events-to-the-semantic-catalog.md) for the full walkthrough.

**3. Deploy**

The new events and their parameters are created **on your branch**. Test them, then deploy to make them live for everyone.

## What Gets Created

| From the Event Catalog | In the Semantic Catalog |
| - | - |
| The raw event | An event named after it |
| Each of its parameters | A parameter on that event |
| Each of its user properties | A parameter on that event |

A raw event whose description is still pending becomes a **Pending** event. The agent can use it straight away, and answers that rely on it are flagged until someone approves it.

## Keeping Events Up to Date

Once an event is in the Semantic Catalog, new parameters join it as you approve them in the Event Catalog — you don't need to sync the raw event again.

Descriptions stay linked in both directions: change one in the Event Catalog or the Semantic Catalog, and the other follows.

## Common Parameters

A parameter that belongs to two or more events — such as `country`, `platform`, or `user_id` — is a **common parameter**. It's a single item shared by all its events, so changing it once changes it everywhere. Common parameters have their own **Common Parameters** tab in the Semantic Catalog.

A parameter that belongs to only one event is specific to that event.

## Changing Events and Parameters

After an event exists, change it in the [Context Builder](https://docs.clarityq.ai/context-layer/building/how-the-context-layer-builder-works.md) like any other component:

* **`/event`** — Update descriptions (one at a time or in batch), add [rules](https://docs.clarityq.ai/context-layer/rules.md), and delete events or parameters.
* **`/parameter`** — Build and fix parameters, and add rules to them.

You don't edit an event's SQL. Instead, describe how to use the event with rules: a required filter, a value to ignore, how to count something.

### Custom Parameters

When a value is worked out from the event's own row — a `CASE` or an `IF` over its columns, or a cleaned-up version of an existing value — add it as a **custom parameter** with `/parameter`.

A custom parameter can only use the event's own row. If the value has to be looked up in another table, keep the key the event already carries and add a **rule** to it explaining which table to look it up in.

## Deleting Events and Parameters

Deleting is a change on your branch, so it takes effect when you deploy. The deploy dialog then offers to also hide the deleted raw events and parameters in the Event Catalog, so they don't reappear the next time ClarityQ syncs your tracking.

To bring a deleted event back, sync its raw event again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.