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

# Metrics

> Standalone business calculations — your KPIs and derived numeric values.

A metric is a standalone business calculation in the Semantic Catalog — a KPI or derived numeric value like revenue, daily active users, conversion rate, or marketing spend.

Unlike dimensions (which belong to entities), metrics are top-level components. Each metric has its own SQL that returns a single number, and the agent combines metrics with dimensions at query time to produce breakdowns and comparisons.

## What a Metric Contains

Each metric has:

* **Name** — A `snake_case` identifier (e.g., `revenue`, `dau`, `conversion_rate`)
* **Description** — What the metric measures in business terms (e.g., *"Total processed cashout amount in dollars over the date window."*)
* **SQL** — A complete, executable query that returns exactly one row with one numeric column

## Time Behavior

Every metric is parameterized for time in one of three ways:

* **Window metric** — Aggregates over a date range selected by the user (e.g., *revenue this month*, *signups in the last 7 days*). This is the most common type.
* **Point metric** — Calculated for a single date or moment (e.g., *DAU on Tuesday*, *active accounts as of March 1*).
* **Timeless metric** — Independent of time entirely (rare — only for genuinely timeless values like *total accounts ever created*).

The agent applies the appropriate date parameters automatically based on the user's question and the date range selected in Ask Anything.

## How the Agent Uses Metrics

When someone asks a question that involves a metric, the agent:

1. Finds the metric by searching the Semantic Catalog
2. Runs the metric's SQL with the appropriate date parameters
3. Combines it with dimensions if the user asked for a breakdown (e.g., *"revenue by country"*)
4. Applies segment filters if requested (e.g., *"revenue for premium users"*)

Because the SQL is pre-defined, everyone gets the same answer to the same question — regardless of who asks.

## Building Metrics

Metrics are created through the [Context Builder](/context-layer/building/building-metrics). You describe what you want to measure, and the agent drafts the SQL, validates it, and saves it to your draft. See [Building Metrics](/context-layer/building/building-metrics) for the full guide.