# AML Metric

> Reference for the AML Metric object — an aggregated business measure that can be defined inside a dataset or as a standalone, reusable definition.

A `Metric` defines an aggregated business measure in [AQL](/as-code/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`](/reference/aml/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](/reference/aml/field#measure). For patterns on organizing reusable metrics, see [Implement Reusable Metric Store](/as-code/aml/use-cases/extend-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](/as-code/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](/reference/aml/number-format) and [Date Format](/reference/aml/date-format).
hidden              | No       | Default `false`. Hides the metric from the Exploration interface when attached. Not a security feature ([reason](/reference/aml/field#should-i-use-the-hidden-property-in-dimensionmeasure-for-data-restriction-purposes)).

## 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:**

```aml title="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:**

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

```aml title="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](/as-code/aql/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](/reference/aql/aggregator-functions).

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

```aml
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:

```aml
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`](/reference/aml/extend):

```aml title="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

```aml title="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"
}
```

```aml title="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](/as-code/aql/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](/as-code/aml/use-cases/extend-metric-store): patterns for organizing standalone metrics, including `PartialDataset` groupings and parameterization with `Func`
- [AML Extend](/reference/aml/extend): the mechanism for attaching standalone metrics to datasets
- [Measure (`field` reference)](/reference/aml/field#measure): the in-model equivalent