> ## 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.

# Syncing Events to the Semantic Catalog

> Promote approved events from the Event Catalog into the Semantic Catalog so the agent can use them in analyses.

Syncing turns an approved event in the Event Catalog into a queryable component in the [Semantic Catalog](/context-layer/semantic-catalog/what-is-the-semantic-catalog). After sync, the agent reaches for the event by name in metrics, segments, and ad-hoc questions, without you having to point at the raw event name in your warehouse.

The sync is a one-way action you trigger when an event is ready — typically after you've described and approved it in the Event Catalog.

## What Gets Created

Each synced event creates the following:

| Source                                  | Becomes                                                                     |
| --------------------------------------- | --------------------------------------------------------------------------- |
| The event itself                        | A [Feature](/context-layer/semantic-catalog/features) named after the event |
| Each of the event's parameters          | A [Dimension](/context-layer/semantic-catalog/dimensions) on that Feature   |
| Each user property carried by the event | A Dimension on that Feature                                                 |

Descriptions and ownership carry over: the event's description becomes the Feature's description, each parameter and user property description becomes the corresponding Dimension's description, and the approver is recorded on the new components.

## Running a Sync

<Steps>
  <Step title="Approve the event">
    Make sure the event is in **Approved** status. Pending events can't be synced — they need an approved description first.
  </Step>

  <Step title="Select events">
    From the Events tab (or the Event page), select one or more events and choose **Sync to Semantic Catalog**.
  </Step>

  <Step title="Choose how to sync">
    A confirmation dialog shows the count of selected events and offers two actions: **Sync and Approve** or **Sync Only** (see below for the difference).
  </Step>

  <Step title="Review the result">
    ClarityQ reports how many events synced successfully, how many were skipped (already synced), and any that failed with the reason.
  </Step>
</Steps>

## Sync and Approve vs Sync Only

| Action               | New component status | Visibility                                                          |
| -------------------- | -------------------- | ------------------------------------------------------------------- |
| **Sync and Approve** | `Approved`           | Available to everyone in your workspace immediately                 |
| **Sync Only**        | `Private`            | Visible only to you in the Semantic Catalog until manually approved |

Use **Sync Only** when you want to review the resulting Feature before exposing it to the rest of the team — for instance, to tweak its name or rework the dimensions before publishing.

## Auto-sync for Parameters and User Properties

Once an event is synced, its parameters and user properties stay in lock-step automatically:

* **Newly approved descriptions** on a parameter or user property attached to a synced event auto-sync as Dimensions on the existing Feature.
* **Newly discovered parameters** on a synced event are added as Dimensions once they're approved.

This keeps the Semantic Catalog current as your catalog fills in, without you having to re-sync the parent event each time.

## Notes

<Note>
  Re-syncing an already-synced event is a no-op — the existing Feature is preserved. To rebuild a Feature (for example, after renaming the event or restructuring its parameters), delete the Feature from the Semantic Catalog and sync the event again.
</Note>

<Note>
  When you edit an event's description after it's been synced, ClarityQ prompts you to update the corresponding Feature's description as well. The same applies to parameter and user property descriptions — you'll be asked whether to update the matching Dimension.
</Note>