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

​
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).
  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.
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.