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, segments, and features 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 →

​
Features

Features represent tracked product events promoted from the Event Catalog. When an event is synced, it becomes a Feature with its parameters available as dimensions. Features 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.

​
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 draft for review and deploy. See Building the Context Layer for the recommended approach.