Dimension (reference)
AQL functions that require a predefined dimension field (model.field_name): why arbitrary expressions are rejected and how to define the right dimension in AML.
Definition
Some functions in AQL require the input to be a reference to a predefined dimension in AML. This means these functions cannot accept arbitrary expressions but only accept AQL in the form of model.field_name.
date_trunc and its short-hand functions (year, month, day etc) are the "exceptions" to this. You can think that they accept a reference to a time dimension and return a reference to a derived time-dimension.
For example, it's perfectly valid to group by users.created_at | year() or date_trunc(users.created_at, 'year'), as these expressions technically return dimension references rather than arbitrary values.
For example, suppose we have the following users model:
Model users {
dimension id {}
dimension first_name {}
dimension last_name {}
dimension email {}
dimension delivered_orders {}
dimension cancelled_orders {}
}When we want to group by the full name, we can't do this:
users | group(concat(users.first_name, " ", users.last_name)) | select(count(users.id))
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
// Error: `group` expects `Dimension` but got `Text`This happens because group only accepts references to dimensions, not arbitrary expressions.
To fix this issue, you must define a users.full_name field to pass into group:
dimension full_name {
definition: @aql concat(users.first_name, " ", users.last_name) ;;
}Then you can use it like this:
users | group(users.full_name) | select(count(users.id))Table Type
The Table type in AQL represents rows and columns returned from a model, where chained transformations keep returning Tables and aggregations produce a Scalar.
Field Type
How AQL's Field type works, what field origin means, how it tracks where a field came from, and why transformations that create new fields lose that origin.