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.

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

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