Skip to content
DocumentationAgents
Agents
Business context
Metrics

Metrics

Metrics give a business calculation a shared name, definition, and source. Use them to keep revenue, activation, or other measures consistent across agent answers and data apps.

Create a metric

  1. Open Knowledge and choose New knowledge → Metric.
  2. Describe what to measure, including the source data, unit, and filters. For example: "Paid revenue in EUR, excluding refunded orders."
  3. Review the draft's description and expression. Use Refine in chat to resolve ambiguity or change the calculation.
  4. Select Save metric when the definition is ready. Rejected or unresolved drafts must be refined before saving.

Drafting does not save a metric. You need permission to manage metrics to save it. Repository-owned definitions are maintained in their source repository.

Import metrics from dbt

Connect a dbt repository and sync its generated artifacts. Supported definitions are validated against the lakehouse and published as semantic views. In Knowledge, open the repository and project to inspect its files and metrics, then open a metric to review its expression and source tables.

Imported knowledge and a queryable metric are different outputs. A definition can remain available as knowledge even when it cannot be published as an executable metric. Check its status and resolve missing tables, unsupported expressions, or access restrictions before relying on it.

Query a metric

Ask your connected agent to call list_semantic_metrics, optionally with a search query. For queryable metrics, it returns runnable SQL and the dimension members available for grouping and filtering. Have the agent execute that SQL with query_lakehouse.

Use the returned metric and dimension names inside SEMANTIC_VIEW(...); keep filters and breakdowns inside that expression so the calculation retains its definition. Prefer the returned query over reconstructing an aggregation from the description.

If a metric has no runnable query, check that its semantic view has been published and that your credentials can read the required catalogs. The expression explains the definition; it is not a replacement for its query.

Related guides