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

# Building Metrics

> How to create, edit, and ship metrics through the Context Builder.

A [metric](/context-layer/semantic-catalog/metrics) is a business calculation the agent can reach for whenever a question calls for it — revenue, daily active users, conversion rate, marketing spend. The **Context Builder** is where you create new metrics, edit existing ones, and adjust how they're calculated.

You can provide as much or as little as you want — a name, description, and SQL, or just a plain-language request. The agent completes whatever is missing, adapts your SQL to ClarityQ standards, validates the result, and saves it to your draft. You review what was created and deploy it when you're ready.

## Starting a Metric

You can start a new metric from three places:

* **Semantic Catalog → Metrics** — Click **Add Metric** in the top right. ClarityQ opens a Builder chat with the command pre-filled.
* **Builder chat directly** — Type `/metric add` in any Builder chat.
* **From an Ask Anything conversation** — If you've been exploring a question in Ask Anything and realize you need a new metric, continue the conversation in the Builder. The agent already has the context of your analysis, so you can type `/metric add` and it will use what you've discussed to build the metric.

## How the Agent Builds the Metric

Describe what you want to measure in plain language — for example, "total cashout amount in dollars" or "daily active users." The agent takes it from there:

1. **Checks for duplicates** — Searches your existing metrics to avoid creating a near-duplicate. If a similar metric already exists, it suggests editing it instead.
2. **Identifies the source** — Finds the right table and column in your Table Catalog and confirms with you.
3. **Determines time behavior** — Figures out whether the metric should aggregate over a date range (e.g., *revenue this month*), apply to a single point in time (e.g., *DAU on Tuesday*), or be time-independent. If the wording is ambiguous, the agent asks a clarifying question.
4. **Writes and validates** — Generates the SQL, validates it against your data, and saves the metric to your draft.

If something doesn't look right — a typo in a column name, an aggregation that doesn't make sense on the chosen column — the agent surfaces the issue and you can correct course in chat.

## Editing and Deleting Metrics

From the **Metrics** tab of the Semantic Catalog:

* **Edit** — Open the metric and click **Edit** in the row menu, or type `/metric edit <metric_name>` in a Builder chat. The agent loads the current definition and walks you through the changes.
* **Delete** — Choose **Delete** from the row menu, or type `/metric delete <metric_name>`. Deletion removes the metric from the catalog once your draft is deployed.

## Adding Several Metrics at Once

Building a dozen metrics one at a time is slow. Two faster paths:

* **List them in the chat** — Ask the agent to add several metrics in one message (*"add installs, marketing\_spend, cashout\_amount, and ARPU"*). Before creating anything the agent shows you a single proposal table — name, description, and the formula for any composites like ARPU — and waits for your confirmation.
* **Attach a file** — Drop a simple `.xlsx` spreadsheet (single tab) or a `.csv` file with your definitions into the Builder message. The agent reads the file, confirms what it understood, and creates the metrics in bulk.

<Tip>
  When uploading a file, include only metrics — don't mix metrics with other component types like entities or segments. This keeps the agent focused and reduces the chance of errors. Bulk creation via chat or file upload works the same way for other component types.
</Tip>

## After Creating

A newly created metric lands in your draft and is only available to you until you deploy. To make a metric live for everyone:

1. **Test in Chat** to spot-check the answer ClarityQ returns when the metric is used (see [How the Context Layer Builder works](/context-layer/building/how-the-context-layer-builder-works#drafts-and-versioning)).
2. **Run the audit** (`/audit-changes`) on your draft so any broken references or validation issues surface before you ship.
3. **Deploy** the draft from the orange banner at the top of the screen. The metric (along with any other draft changes) becomes part of the published catalog and available to everyone in your organization.

<Tip>
  When a question could be answered with an existing metric instead, the agent flags the overlap and offers to edit the existing metric rather than create a near-duplicate. Lean into that — fewer, well-defined metrics keep the catalog easier to reason about.
</Tip>