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

# Dimensions

> Properties used to filter and group data in your analyses.

A dimension is any property that describes an [entity](/context-layer/semantic-catalog/entities). 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](/context-layer/building/how-the-context-layer-builder-works), 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.