Skip to main content
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:
  • 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)
  • Rules — Optional instructions the agent must follow whenever it uses this entity, such as a filter that must always be applied (see Rules)

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

​
Rules on Entities

An entity can carry Rules — named instructions the agent must follow whenever it uses that entity. They hold the constraints that keep it queried correctly: required filters, business logic, and data-quality caveats. For example, on a users entity: Exclude test accounts — “Always filter is_test = false. Internal QA accounts are otherwise counted as real users.” A rule on an entity also reaches its dimensions. When the agent uses one of the entity’s dimensions on its own, it still sees the entity’s rules and its base query — so a required filter can’t be dropped by coming at the data from a dimension. That makes the entity the right home for any filter that must apply to everything built on it. Rules are managed from the Rules section on the entity’s page. See Rules for how adding and editing works.