AML Metric

A Metric defines an aggregated business measure in AQL. The same Metric type can be defined in two places:

• Inline inside a dataset — quickest if the metric is only used by one dataset.
• Standalone at the top level — reusable; attach the same definition to multiple datasets via extend.

Both forms share the same parameters and the same definition semantics. For an in-model equivalent (a measure defined inside a Model), see Measure. For patterns on organizing reusable metrics, see Implement Reusable Metric Store.

Parameter definition

Parameter name	Required	Description
label	Yes	How the metric appears in the Ready-to-explore Dataset.
type	Yes	Data type of the metric's result. Possible values: 'text', 'number', 'date', 'datetime', 'truefalse', 'json', 'unknown'. Typically 'number'.
definition	Yes	The metric expression, written in AQL. Must produce an aggregated value. AQL only — unlike a measure, a standalone Metric cannot use @sql.
description	No	Describes the semantic of the metric. Surfaced in tooltips in the exploration UI.
format	No	Display format for the metric's value. See Number Format and Date Format.
hidden	No	Default false. Hides the metric from the Exploration interface when attached. Not a security feature (reason).

Where to define

The body of a Metric is identical whether you write it inline in a dataset or as a standalone top-level object.

Inline in a dataset:

ecommerce.dataset.aml

Dataset ecommerce {
  // ... models, relationships, dimensions ...

  metric count_orders {
    label: "Count Orders"
    type: "number"
    definition: @aql count(orders.id) ;;
  }

  metric sum_order_value {
    label: "Sum Order Values"
    type: "number"
    definition: @aql sum(order_items, order_items.quantity * products.price) ;;
  }
}

Standalone, then attached to a dataset:

metrics.aml

Metric count_orders {
  label: "Count Orders"
  type: "number"
  definition: @aql count(orders.id) ;;
}

ecommerce.dataset.aml

Dataset ecommerce_with_metrics = ecommerce.extend({
  metric count_orders: count_orders
})

Prefer the standalone form when the same metric is needed across more than one dataset — change the definition once and every dataset that references it picks up the update. See Where to define AQL for a fuller comparison.

Definition

A Metric's definition is written in AQL (@aql ... ;;). Like a measure, it must produce an aggregated value (use sum(), count(), avg(), etc., or reference another metric that does). For the full list of aggregators, see Aggregation Functions.

Standalone metrics reference models and dimensions directly by name; they are not scoped to a single model.

Metric gmv {
  label: "GMV (Gross Merchandise Value)"
  type: "number"
  description: "Total value of all orders before discount"
  definition: @aql ecommerce_order_items | sum(ecommerce_order_items.quantity * ecommerce_products.price) ;;
  format: "[\$\$]#,###0"
}

A metric can reference another metric in its definition, letting you build derived metrics:

Metric total_orders {
  label: "Total Orders"
  type: "number"
  definition: @aql count(ecommerce_orders.id) ;;
}

Metric aov {
  label: "AOV (Average Order Value)"
  type: "number"
  definition: @aql gmv / total_orders ;;
  format: "[\$\$]#,###0"
}

Attaching to a dataset

A standalone Metric becomes usable in exploration only after it's attached to a dataset via extend:

sales.dataset.aml

Dataset sales_with_metrics = sales.extend({
  metric gmv: gmv
  metric total_orders: total_orders
})

The same metric can be attached to any number of datasets. Change the Metric definition once, and every dataset that references it picks up the update.

Example

metrics.aml

Metric total_orders {
  label: "Total Orders"
  type: "number"
  description: "Total number of orders placed"
  definition: @aql count(ecommerce_orders.id) ;;
}

Metric gmv {
  label: "GMV (Gross Merchandise Value)"
  type: "number"
  description: "Total value of all orders before discount"
  definition: @aql ecommerce_order_items | sum(ecommerce_order_items.quantity * ecommerce_products.price) ;;
  format: "[\$\$]#,###0"
}

Metric aov {
  label: "AOV (Average Order Value)"
  type: "number"
  definition: @aql gmv / total_orders ;;
  format: "[\$\$]#,###0"
}

company.dataset.aml

Dataset company_with_metrics = company.extend({
  metric total_orders: total_orders
  metric gmv: gmv
  metric aov: aov
})

See also

• Where to define AQL: all the places a metric can live (in a model, in a dataset, standalone, or ad-hoc)
• Implement Reusable Metric Store: patterns for organizing standalone metrics, including PartialDataset groupings and parameterization with Func
• AML Extend: the mechanism for attaching standalone metrics to datasets
• Measure (field reference): the in-model equivalent