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.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.
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:- Finds the revenue metric
- Applies the country dimension from the relevant entity
- Filters to the premium users segment
- Builds and runs the SQL