Defining a metric

So far we've been writing aggregations inline. That's the explore style: write an AQL expression directly into a report and get an answer. The moment you want to reuse the same aggregation elsewhere, you give it a name and stash it somewhere. That's a metric.

The two are a pair. An explore expression is a one-shot AQL query. A metric is the same expression named and saved, ready to be referenced from any report. Same language, two ways to use it.

Try it interactively

Practice in the AQL Playground: Reading & Writing Metrics.

The simplest possible metric

Model orders {
  measure total_orders {
    label: 'Total Orders'
    type: 'number'
    definition: @aql count(orders.id) ;;
  }
}

Now anywhere you used to write count(orders.id), you can just write orders.total_orders. Reports show the same number. Change the formula here once, every report updates.

This is the "same metric, three reports" behavior previewed in What AQL Is For. You've now seen the syntax that makes it work. Metric Context (next page) explains how the adaptation actually happens.

Metrics can include their own filter

You can bake a where() into the definition. The filter rides with the metric:

measure female_user_count {
  definition: @aql count(users.id) | where(users.gender == 'Female') ;;
}

Anywhere female_user_count shows up, it only counts women. No caller has to remember the filter.

Metrics compose

Once you have a few base metrics, you can build new ones from them:

metric orders_per_user {
  definition: @aql total_orders / total_users ;;
}

This is the heart of the language. You build a small vocabulary of trusted metrics, then derive everything else from them.

Dimensions can be defined in AQL too

The same naming pattern works for dimensions: a "virtual column" derived from an AQL expression. Useful when a piece of row-level logic gets reused across reports.

dimension is_electronics {
  model: products
  label: 'Is Electronics'
  type: 'truefalse'
  definition: @aql categories.name ilike '%Electronics%' ;;
}

Now any report can filter or group by products.is_electronics instead of repeating the ilike expression. Same idea as a metric, just at row grain instead of aggregate grain.

Two homes for a metric

Holistics uses two words deliberately: a measure is defined on a model, a metric is defined on a dataset. They're the same kind of thing (a named, reusable AQL expression) at different scopes.

• In a model as a measure {} when the metric is naturally tied to that one table.
• In a dataset as a metric {} when the metric spans multiple models (e.g. revenue = sum of order_items.quantity * products.price).

For when to use which, see Where to Define AQL.

Next

→ Metric context: why the same metric returns different numbers in different reports, and how to control that.