Reference / AQL

AQL Core Shapes

Use this when deciding what kind of AQL to write: metric expression, table expression, or explore expression.

Metric expression

Returns an aggregate value whose result changes with report context.

count(orders.id)

sum(order_items.quantity * products.price)

Best home for reusable business logic.

Returns rows. Use pipeline steps for filtering, grouping, and selecting columns.

orders
  | group(orders.created_at | month())
  | select(
      order_month: orders.created_at | month(),
      total_orders: count(orders.id)
    )

Best when you need explicit row/table shape.

Report query. Holistics chooses source table from dimensions and measures.

explore {
  dimensions {
    countries.name
  }
  measures {
    revenue
  }
  filters {
    orders.created_at matches @2024
  }
}

Best for dashboard/report-level questions.

If business definition is wrong, inspect metric expression.
If rows or grouping are wrong, inspect table/explore shape.
If cross-model values are wrong, inspect dataset relationships.
If same metric differs by report, inspect metric context: dimensions, filters, relationships, level of detail, windows.