Skip to main content
The Semantic Catalog is where your business logic lives in ClarityQ. It’s a structured collection of components that define how your organization thinks about its data — not in terms of tables and columns, but in terms of business concepts like revenue, active users, churn, and conversion. When someone asks a question in Ask Anything, the agent searches the Semantic Catalog first. It finds the relevant definitions, uses them to build accurate SQL, and returns answers grounded in your team’s agreed-upon business logic.

Why It Matters

Without a Semantic Catalog, the agent would have to guess what “revenue” or “active user” means by looking at raw tables. Different people might get different answers to the same question depending on which table the agent picks or how it interprets a column. The Semantic Catalog eliminates that ambiguity. When your team defines “revenue” as a metric with specific SQL, every question about revenue uses that exact definition — consistently, for everyone.

Components

The Semantic Catalog contains five types of components:

Entities

Entities represent your core data sources — the tables or views that contain the data your team queries. Each entity has a name, description, SQL definition, and a set of dimensions that describe its columns. Entities are the foundation that metrics and segments build on. Learn more →

Dimensions

Dimensions are the properties that describe an entity — anything you can say about it. They serve as attributes, measures, and grouping axes all in one. Country, platform, plan type, revenue amount, session duration, signup date — these are all dimensions. They belong to entities and are used for filtering, grouping, and analysis. Learn more →

Metrics

Metrics are standalone business calculations — KPIs and derived numeric values like revenue, daily active users, or conversion rate. Each metric has its own SQL that returns a single number, and can be combined with dimensions at query time for breakdowns. Learn more →

Events

Events represent tracked user actions, synced from raw events in the Event Catalog. Each event comes with its parameters — the properties recorded with it — which can be used for filtering and grouping. Events answer questions about user behavior: what happened, how often, and with what properties. Learn more →

Segments

Segments are reusable cohort definitions — named groups of users matching specific criteria. Each segment has SQL that returns a distinct list of user identifiers. Once defined, segments can be applied to any question as a filter. Learn more →

How Components Work Together

The agent combines components at query time to answer questions. For example, when someone asks “what was revenue last week by country for premium users?”, the agent:
  1. Finds the revenue metric
  2. Applies the country dimension from the relevant entity
  3. Filters to the premium users segment
  4. Builds and runs the SQL
No one has to pre-build that specific combination — the Semantic Catalog makes it composable.

Component Status

Every component carries a status: The agent uses Pending components. You don’t have to approve everything before your team can ask questions — a suggested metric is available straight away, and you close the gaps as they surface rather than up front. When an answer relies on a Pending component, it’s flagged in that answer’s context coverage and listed in the Inbox until someone approves it. So nothing is hidden: you see exactly which answers leaned on unverified definitions. Approving a component, or editing its description on its catalog page, goes live for everyone right away. You don’t need to deploy. The one exception is a component your branch has already changed: then the change is saved to your branch. See Changes That Go Live Right Away.

Where a Definition Came From

Components you define yourself — metrics, segments, skills, entities, and custom dimensions — show a Source telling you where the definition originated. Events and their parameters are different, because they arrive from the Event Catalog. They carry over whatever confidence the raw event or parameter had when you synced it. If you synced something whose description was still Inferred or Needs input, the event or parameter shows that same label here — so an unverified description stays visible as unverified, rather than looking settled once it reaches the Semantic Catalog. See Where a Description Came From for what each value means.

Rules on Components

Any component — an entity, metric, dimension, segment, event, or parameter — can carry Rules: named instructions the agent must follow whenever it uses that component, such as a required filter or a data-quality caveat. Rules travel with the component and are applied automatically, so the right constraints are enforced no matter how a question reaches the item.

Building the Semantic Catalog

Components are created and managed through the Context Builder. The agent helps you build them — you describe what you need, and it drafts the definition, validates the SQL, and saves it to your branch. It goes live for everyone when you deploy. See Building the Context Layer for the recommended approach.