AQL Cheatsheet - Functions
Aggregate Function
count()
Syntax
count([table], expression)
Description
Counts the total number of items in a group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
orders
| count(orders.id)
orders
| count(orders.id)
| where(orders.status == 'completed')
orders
| group(orders.delivery_country)
| select(orders.delivery_country, total_orders: count(orders.id))
Inputs
- expression (Any: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The count of non-NULL values.
Learn more
count_if()
Syntax
count_if([table], condition)
Description
Counts the total rows from one table that satisfy the given condition.
Tags
Function, Aggregate Function, Condition
Examples
orders
| count_if(orders.delivery_country == 'USA')
orders
| count_if(orders.status == 'shipped')
orders
| group(orders.delivery_country)
| select(orders.delivery_country, shipped_orders: count_if(orders.status == 'shipped'))
Inputs
- condition (Truefalse: required): A field or an AQL expression that evaluates to true or false.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The count of rows that satisfy the condition.
Learn more
count_distinct()
Syntax
count_distinct([table], expression)
Description
Counts the total number of distinct items in a group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
orders
| count_distinct(orders.customer_id)
customers
| count_distinct(customers.id)
| where(customers.country == 'USA')
products
| group(products.id)
| select(products.id, total_countries: count_distinct(orders.delivery_country))
Inputs
- expression (Any: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The count of distinct non-NULL values.
Learn more
average()
Syntax
average([table], expression)
Description
Calculates the average of values in a group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
orders
| average(orders.value)
orders
| average(orders.value)
| where(orders.status == 'completed')
orders
| group(orders.delivery_country)
| select(orders.delivery_country, avg_order_value: average(orders.value))
Inputs
- expression (Number: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The average of the values.
Aliases
avg()
Learn more
min()
Syntax
min([table], expression)
Description
Returns the item in the group with the smallest value, excluding NULL values.
Tags
Function, Aggregate Function
Examples
orders
| min(orders.value)
orders
| min(orders.value)
| where(orders.status == 'completed')
orders
| group(orders.delivery_country)
| select(orders.delivery_country, min_order_value: min(orders.value))
Inputs
- expression (Any: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Any: The minimum value.
Learn more
max()
Syntax
max([table], expression)
Description
Returns the item in the group with the largest value, excluding NULL values.
Tags
Function, Aggregate Function
Examples
orders
| max(orders.value)
orders
| max(orders.value)
| where(orders.status == 'completed')
orders
| group(orders.delivery_country)
| select(orders.delivery_country, max_order_value: max(orders.value))
Inputs
- expression (Any: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Any: The maximum value.
Learn more
sum()
Syntax
sum([table], expression)
Description
Calculates the sum of values in the group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
orders
| sum(orders.value)
orders
| sum(orders.value)
| where(orders.status == 'completed')
orders
| group(orders.delivery_country)
| select(orders.delivery_country, total_order_value: sum(orders.value))
Inputs
- expression (Number: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The sum of the values.
Learn more
median()
Syntax
median([table], expression)
Description
Computes the median of the values in the group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
median(orders.quantity)
orders
| median(orders.quantity)
Inputs
- expression (Number: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The median of the values.
Learn more
stdev()
Syntax
stdev([table], expression)
Description
Computes the sample standard deviation of the values in the group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
stdev(orders.value)
orders
| stdev(orders.value)
Inputs
- expression (Number: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The sample standard deviation.
Learn more
stdevp()
Syntax
stdevp([table], expression)
Description
Computes the population standard deviation of the values in the group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
stdevp(orders.value)
orders
| stdevp(orders.value)
Inputs
- expression (Number: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The population standard deviation.
Learn more
var()
Syntax
var([table], expression)
Description
Returns the sample variance of the values in the group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
var(orders.value)
orders
| var(orders.value)
Inputs
- expression (Number: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The sample variance.
Learn more
varp()
Syntax
varp([table], expression)
Description
Returns the population variance of the values in the group, excluding NULL values.
Tags
Function, Aggregate Function
Examples
varp(orders.value)
orders
| varp(orders.value)
Inputs
- expression (Number: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
Output
- Number: The population variance.
Learn more
string_agg()
Syntax
string_agg([table], expression, [sep: _sep], [distinct: _distinct], [order: _order])
Description
Returns a text that is the concatenation of all values of the expression.
Tags
Function, Aggregate Function
Examples
string_agg(products.name)
string_agg(products.name, sep: ', ')
string_agg(products.name, sep: ', ', distinct: true)
string_agg(products.name, order: 'asc')
string_agg(products.name, order: 'desc')
Inputs
- expression (Text: required): A field or an AQL expression to be evaluated in each row of the table to be aggregated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
- _sep (Text: optional): Separator between values, default is
','
. - _distinct (Truefalse: optional): If true, only distinct values are concatenated, default is
false
. - _order (Text: optional): Specifies the ordering of values ('asc' or 'desc'), default is not specified.
Output
- Text: The concatenated text of values.
Learn more
corr()
Syntax
corr(table, field1, field2)
Description
Returns the Pearson correlation coefficient of two number fields in the table.
Tags
Function, Aggregate Function
Examples
corr(users, users.age, orders.value)
Inputs
- table (Table: required): The table containing the fields to correlate.
- field1 (Number: required): The first number field to correlate.
- field2 (Number: required): The second number field to correlate.
Output
- Number: The Pearson correlation coefficient between the two fields.
Learn more
max_by()
Syntax
max_by(table, value, by)
Description
Returns the value of value
from the row where by
is maximum.
Tags
Function, Aggregate Function
Examples
max_by(orders, orders.customer_name, orders.value)
Inputs
- table (Table: required): The table to find the maximum value in.
- value (Any: required): The field to return from the row with the maximum value.
- by (Any: required): The expression to use for determining the maximum value.
Output
- Any: The value of
value
from the row whereby
is maximum.
Learn more
min_by()
Syntax
min_by(table, value, by)
Description
Returns the value of value
from the row where by
is minimum.
Tags
Function, Aggregate Function
Examples
min_by(orders, orders.customer_name, orders.value)
Inputs
- table (Table: required): The table to find the minimum value in.
- value (Any: required): The field to return from the row with the minimum value.
- by (Any: required): The expression to use for determining the minimum value.
Output
- Any: The value of
value
from the row whereby
is minimum.
Learn more
percentile_cont()
Syntax
percentile_cont([table], expression, percentile)
Description
Returns the value at the given percentile of the sorted expression values, interpolating between adjacent values if needed.
Tags
Function, Aggregate Function
Examples
percentile_cont(ecommerce_users.age, 0.7)
ecommerce_users | percentile_cont(ecommerce_users.age, 0.7)
unique(ecommerce_users.id) | percentile_cont(total_value, 0.7)
Inputs
- expression (Any: required): A field or an AQL expression to be evaluated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
- percentile (Number: required): The percentile to compute. Must be a value between 0 and 1.
Output
- Any: The percentile value.
Learn more
percentile_disc()
Syntax
percentile_disc([table], expression, percentile)
Description
Returns the value at the given percentile of the sorted expression values. If the percentile falls between two values, a discrete value will be returned (the logic to select the value is database dependent).
Tags
Function, Aggregate Function
Examples
percentile_disc(ecommerce_users.age, 0.7)
ecommerce_users | percentile_disc(ecommerce_users.age, 0.7)
unique(ecommerce_users.id) | percentile_disc(count(ecommerce_orders.id), 0.7)
Inputs
- expression (Any: required): A field or an AQL expression to be evaluated.
- table (Table: optional): The table to aggregate. It's only optional when the table can be inferred from the expression.
- percentile (Number: required): The percentile to compute. Must be a value between 0 and 1.
Output
- Any: The percentile value.
Learn more
Condition Function
where()
Syntax
where(metric, condition1, [condition2, ...])
metric | where(condition1, [condition2, ...])
Description
Calculates a metric with specified conditions applied. The where
function allow applying conditions to a metric without needing to manually modifying its original definition and filters data at the source before any calculations occur. It works similar to Dashboard Filters.
Difference vs filter: where
pushes conditions down to the target model before calculations begin. In contrast, filter
evaluates conditions locally after retrieving the data. Due to this key difference, condition in where
can only target pre-defined dimension in modeling, and only support some form of conditions. For more information, please check the full documentation.
Tags
Function, Metric Function, Condition Function, Condition
Examples
total_order_value
| where(orders.status == 'completed')
total_order_value
| where(users.id in top(5, users.id, by: count(orders.id)))
sum(orders.value)
| where(orders.created_at matches @(last 30 days))
Inputs
- metric (Any: required): The original metric to which the condition will be applied.
- condition1 (Condition: required): The condition to restrict the metric calculation.
- [condition2, ...] (Condition: optional, repeatable): Additional conditions to apply.
Output
- Any: The original metric calculated with the specified conditions applied.
Learn more
Level Of Detail Function
of_all()
Syntax
of_all(metric, [model, dimension, ...], [keep_filters: false])
metric | of_all([model, dimension, ...], [keep_filters: false])
Description
Returns a metric evaluated without certain dimensions or grains. The of_all
function removes specified dimensions from the calculation context. It is commonly used for calculating percent of total and enables comparisons between metrics at different Levels of Detail (LoD). The function has aliases exclude_grains
and exclude
that provides identical functionality.
Tags
Function, Metric Function, Level of Detail Function
Examples
order_value / (
order_value
| of_all(order_items.country)
)
count(orders.id)
| of_all(orders.category)
order_value - (avg(unique(order_items.country)
| select(order_value))
| of_all(order_items.country))
Inputs
- metric (Any: required): The metric to exclude dimensions from.
- model (Model: optional, repeatable): Model whose dimensions should be excluded.
- dimension (Dimension: optional, repeatable): Specific dimensions to exclude.
- keep_filters (Truefalse: optional): Whether to keep filters applied on excluded dimensions. Default is false.
Output
- Any: The original metric calculation without the specified dimensions.
Aliases
exclude_grains(), exclude()
Learn more
keep_grains()
Syntax
keep_grains(metric, [model, dimension, ...], [keep_filters: false])
metric | keep_grains([model, dimension, ...], [keep_filters: false])
Description
Calculates a metric only against the specified dimensions or grains, ignoring all other dimensions. The keep_grains
function ensures that calculations maintain a consistent level of detail, prevents additional query fields from affecting the metric, and works only with dimensions already present in the context. Note that it will not add the grains to the Level of Detail context if they aren't present before calling keep_grains
.
Tags
Function, Metric Function, Level of Detail Function
Aliases
keep()
Examples
// This keeps the grain of the entire user model during the metric calculation
sum(order_items.order_value)
| keep_grains(users)
average_order_value
| keep_grains(users.id)
Inputs
- metric (Any: required): The input metric to modify.
- model (Model: optional, repeatable): Model whose dimensions should be kept.
- dimension (Dimension: optional, repeatable): Specific dimensions to keep.
- keep_filters (Truefalse: optional): Whether to keep filters applied on excluded dimensions. Default is false.
Output
- Any: The original metric calculation using only the specified dimensions.
Learn more
dimensionalize()
Syntax
dimensionalize(metric, [dimension, ...])
metric | dimensionalize([dimension, ...])
Description
Calculates a metric at a specific Level of Detail (LoD), regardless of the outer query context. The dimensionalize
function evaluates metrics at a fixed grain and turns the result into a dimension value. It is commonly used for cohort analysis and customer lifetime value calculations, and only works inside dimension definitions.
Difference vs keep_grains: Unlike keep_grains
which retains specified grains in metric calculation, dimensionalize
evaluates the calculation at specified grains and converts it into a dimension value. It only works inside dimension definitions.
Tags
Function, Metric Function, Level of Detail Function
Examples
sum(orders.amount)
| dimensionalize(users.id)
min(users.created_at | month())
| dimensionalize(users.id)
Inputs
- metric (Any: required): The metric to evaluate at a fixed grain.
- dimension (Dimension: optional, repeatable): The dimension(s) to use as the Level of Detail.
Output
- Any: The metric value at the specified granularity as a dimension value.
Learn more
Logical Function
case()
Syntax
case(when: condition, then: value, [when: condition_expr, then: value, ...], [else: value])
Description
Returns the value associated with the first condition that evaluates to true. Note that the return types of all then
and else
expressions must be consistent.
Tags
Function, Logical Function, Condition
Examples
case(
when: users.gender == 'm', then: 'male',
when: users.gender == 'f', then: 'female',
else: 'others'
)
Inputs
- when (Truefalse: required): The condition to evaluate.
- then (Any: required): The value to return if the condition is met.
- else (Any: optional): The value to return if no conditions are met.
Output
- Any: The value returned based on the first met condition, or the else value if provided and no conditions are met.
Learn more
and()
Syntax
and(condition, ...)
Description
Returns true only when all specified conditions are true.
Tags
Function, Logical Function, Condition
Examples
and(products.id >= 2, products.id <= 8)
Inputs
- condition (Truefalse: required, repeatable): The conditions to AND together.
Output
- Truefalse: Returns true if all input conditions are true, else false.
Learn more
or()
Syntax
or(condition, ...)