Skip to main content
A dimension is any property that describes an entity. Dimensions serve as attributes, measures, and grouping axes all in one — country, platform, plan type, revenue amount, session duration, signup date are all dimensions. The agent uses dimensions to filter, group, and analyze data. When someone asks “break down revenue by country”, the agent uses the country dimension. When someone asks “show me only iOS users”, it applies the platform dimension as a filter.

​
What a Dimension Contains

Each dimension has:
  • Name — A snake_case identifier (e.g., country, platform, plan_type)
  • Description — What the dimension represents and how it can be used for analysis (e.g., “Country the user is in. Filter cohorts, group revenue by country.”)
  • SQL — A fully qualified SQL statement that selects this dimension from the entity’s data sources
  • Type — The data type (e.g., VARCHAR, INTEGER, DATE)
  • Data sample — A few real values from the data (e.g., "US", "UK", "DE") to help the agent understand the domain
  • Rules — Optional instructions the agent must follow whenever it uses this dimension (see Rules)

​
How Dimensions Are Created

Dimensions can be created in several ways:
  • During entity creation — When you build an entity through the Context Builder, the agent inspects the source tables and proposes dimensions for columns useful for filtering and analysis.
  • From the Table Catalog — Select columns from a table and choose an existing entity to add them to as dimensions.
  • In the Builder chat — Type /dimension add to add a dimension to an existing entity.
Not every column needs to be a dimension. Focus on columns your team actually uses for filtering and analysis. Internal IDs, raw timestamps, and technical fields can usually be left out.

​
How the Agent Uses Dimensions

The agent combines dimensions with metrics and segments at query time:
  • Grouping — “revenue by country” → the agent adds country to the GROUP BY
  • Filtering — “only premium users” → the agent adds a WHERE clause using the relevant dimension
  • Breakdowns — “compare iOS vs Android” → the agent groups by platform and presents the comparison
The data sample helps the agent understand valid values — so when a user says “US” the agent knows to filter country = 'US' rather than guessing.

​
Rules on Dimensions

A dimension can carry Rules — named instructions the agent must follow whenever it uses that dimension. For example, on a plan_type dimension: Trials are not free users — “trial is a separate plan. Never fold trial users into free when grouping or filtering by plan.” When the agent uses a dimension it also picks up the rules and base query of the entity the dimension belongs to. So a filter that applies to the whole entity belongs on the entity, and a dimension rule is for what’s true of that property alone — its valid values, how it should be grouped, or a quirk in how it was recorded. Rules are managed from the Rules section on the dimension’s page. See Rules for how adding and editing works.