Skip to main content

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.

An entity represents a business concept in your Semantic Catalog — users, orders, sessions, transactions, campaigns. Unlike tables in your data warehouse, which reflect how your data is stored, entities reflect how your business thinks about the data. An entity can draw from one or multiple tables. For example, a users entity might join your accounts table with your profiles table and your subscriptions table to create a single, complete view of a user. The entity’s SQL contains the necessary joins, so the rest of the Semantic Catalog works with the business concept — not the underlying table structure. Entities are the foundation of the Semantic Catalog. Metrics query data from entities, segments filter users defined by entities, and dimensions belong to entities.

​
What an Entity Contains

Each entity has three parts:
  • Name — A snake_case identifier describing the business concept (e.g., users, sessions, transactions)
  • Description — A plain-language explanation of what the entity represents and what each row means (e.g., “One row per user account. Contains profile data, signup info, and account status.”)
  • SQL — A fully qualified SELECT statement that defines the entity’s data, including any joins across multiple tables
  • Dimensions — The properties on this entity that can be used for filtering, grouping, and analysis (see Dimensions)

​
How Entities Are Created

Entities are built through the Context Builder — either from the Table Catalog or from scratch.
  • From the Table Catalog — Select one or more tables from the Table Catalog and ask the agent to turn them into entities. The agent inspects the tables, understands their structure, and creates the entity with the appropriate joins and dimensions. See Building Entities from Tables.
  • In the Builder chat — Type /entity add and specify the tables you want to create entities from. The agent inspects the tables, samples the data, and proposes entity definitions with dimensions.
The agent validates that the source table exists, checks the data grain (what each row represents), and warns about potential issues like missing filters or ambiguous joins.

​
How the Agent Uses Entities

When answering questions, the agent searches for relevant entities, uses their SQL as the data source, and applies the entity’s dimensions for filtering and grouping. The entity’s description helps the agent decide which entity to use when multiple sources could answer a question.