Metrics

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
• Rules — Optional instructions the agent must follow whenever it uses this metric, such as what the number leaves out (see Rules)

​

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.

​

Rules on Metrics

A metric can carry Rules — named instructions the agent must follow whenever it uses that metric. For example, on a revenue metric: Revenue is gross — “This metric does not subtract refunds. When a question asks about net revenue, say so rather than presenting this number as net.” Rules are the place for the caveats you’d otherwise repeat in every question: what the number does and doesn’t include, a currency assumption, or a date before which the data is incomplete. Rules are managed from the Rules section on the metric’s page. See Rules for how adding and editing works.

​

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.