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 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. You describe what you want to measure, and the agent drafts the SQL, validates it, and saves it to your draft. See Building Metrics for the full guide.