Grouping Reference
Read the Vespa grouping guide first, for examples and an introduction to grouping - this is the Vespa grouping reference.
Refer to groupingSessionCache for grouping performance. Also note that using a multivalued attribute (such as an array of doubles) in a grouping expression affects performance. Such operations can hit a memory bandwidth bottleneck, particularly if the set of hits to be processed is large, as more data is evaluated.
group
Group query results using a custom expression (using the group
clause):
- A numerical constant
- A document attribute
-
A function over another expression (
xorbit
,md5
,cat
,xor
,and
,or
,add
,sub
,mul
,div
,mod
) or any other expression - The data type of an expression is resolved using best effort, similarly to how common programming languages does to resolve arithmetics of different data typed operands
-
The results of any expression are either scalar or single dimension arrays
add(<array>)
adds all elements together to produce a scalar-
add(<arrayA>, <arrayB>)
adds each element together producing a new array whose size ismax(|<arrayA>|, |<arrayB>|)
Groups can contain subgroups (by using each
and group
operations),
and may be nested to any level.
Multiple sub-groupings or outputs can be created under the same group level, using multiple parallel each
or all
clauses, and each one may be labelled using as(mylabel)
.
When grouping results, groups that contain outputs, group lists and hit lists are generated. Group lists contain sub-groups, and hit lists contain hits that are part of the owning group.
The identity of a group is held by its id. Scalar identities such as long, double and string, are directly available from the id, whereas range identities used for bucket aggregation are separated into the sub-nodes from and to. Refer to the result format reference.
Multivalue attributes
A multivalue attribute is a weighted set, array or map. Most grouping functions will just handle the elements of multivalued attributes separately, as if they were all individual values in separate documents. The following syntax can be used when grouping on map attribute fields.
Group on map keys:
all( group(mymap.key) each(output(count())) )Group on values for key my_key:
all( group(my_map{"my_key"}) each(output(count())) )Group on struct field my_field referenced in map element my_key:
all( group(my_map{"my_key"}.my_field) each(output(count())) )The key can either be specified directly (above) or indirectly via a key source attribute. The key is retrieved from the key source attribute for each document. Note that the key source attribute must be single value and have the same data type as the key type of the map. Using a key source attribute is not supported for streaming search:
all( group(my_map{attribute(my_key_source)}) each(output(count())) )
Tensors can not be used in grouping.
order
Each level of grouping may specify how to order its groups (using order
):
- Ordering can be done using any of the available aggregates
- Multi-level grouping allows strict ordering where primary aggregates may be equal
- Ordering is either ascending or descending, specified per level of ordering
- Groups are sorted using locale aware sorting
Limit the number of groups returned for each level using max
,
returning only first n groups as specified by order
:
-
order
changes ordering of groups after a merge operation for the following aggregators:count
,avg
andsum
-
order
will not change ordering of groups after a merge operation whenmax
ormin
is used -
Default order,
max(relevance())
, does not require use ofprecision
continuations
Pagination of grouping results are managed by continuations
.
These are opaque objects that can be combined and re-submitted using the continuations
annotation
on the grouping step of the query to move to the previous or next page in a result list.
All root groups contain a single this continuation per select
.
That continuation represents the current view, and if submitted as the sole continuation,
it will reproduce the exact same result as the one that contained it.
There are zero or one prev/next continuation per group- and hit list. Submit any number of these to retrieve the next/previous pages of the corresponding lists
Any number of continuations can be combined in a query, but the first must always be the this continuation. E.g. one may simultaneously move both to the next page of one list, and the previous page of another.
Note: If more than one continuation object are provided for the same group- or hit-list, the one given last is the one that takes effect. This is because continuations are processed in the order given, and they replace whatever continuations they collide with.
If working programmatically with grouping, find the
Continuation
objects within
RootGroup
,
GroupList
and
HitList
result objects. These can then be added back into the continuation list of the
GroupingRequest
to paginate.
Refer to the grouping guide for an example.
Labels
Lists created using the each
keyword can be assigned a label
using the construct each(...) as(mylabel)
.
The outputs created by that each clause will be identified by this label.
where(true)
Only results matching the query are grouped, also in streaming search - with one exception:
Using where(true)
in the grouping expression groups all documents
matching the selection string
in the Query API. Example:
all( where(true) all(group(myfield) each(output(count()))) )When using
where(true)
, relevancy is not calculated for groups, as only matched hits have relevance.
Refer to streaming search grouping for an example.
Aggregators
Each level of grouping specifies a set of aggregates to collect for all documents
that belong to that group (using the output
operation):
- The documents in a group, retrieved using a specified summary class
- The count of documents in a group
- The sum, average, min, max, xor or standard deviation of an expression
When using order
, aggregators can also be used in expressions in order to get increased control over group sorting.
This does not work with expressions that takes attributes as an argument, unless the expression is enclosed within an aggregator.
Using sum, max on a multivalued attribute:
Doing an operation such as output(sum(myarray))
will run the sum over each element value in each document.
The result is the sum of sums of values.
Similarly max(myarray)
will yield the maximal element over all elements in all documents, and so on.
Multivalue fields such as maps, arrays can be used for grouping.
However, using aggregation functions such as sum() on such fields can give misleading results.
Assume a map from strings to integers (map<string, int>
),
where the strings are some sort of key to use for grouping.
The following expression will provide the sum of the values for all keys:
all( group(mymap.key) each(output(sum(mymap.value))) )and not the sum of the values within each key, as one would expect. It is still, however, possible to run the following expression to get the sum of values within a specific key:
all( group("my_group") each(output(sum(mymap{"foo"}))) )Refer to the system test for grouping on struct and map types for more examples.
Group list aggregators | |||
Name | Description | Arguments | Result |
---|---|---|---|
count | Counts the number of unique groups (as produced by group ).
Note that count operates independently of max and that this count is an estimate using HyperLogLog++ which is an algorithm for the count-distinct problem | None | Long |
Group aggregators | |||
Name | Description | Arguments | Result |
count | Increments a long counter everytime it is invoked | None | Long |
sum | Sums the argument over all selected documents | Numeric | Numeric |
avg | Computes the average over all selected documents | Numeric | Numeric |
min | Keeps the minimum value of selected documents | Numeric | Numeric |
max | Keeps the maximum value of selected documents | Numeric | Numeric |
xor | XOR the values (their least significant 64 bits) of all selected documents | Any | Long |
stddev | Computes the population standard deviation over all selected documents | Numeric | Double |
Hit aggregators | |||
Name | Description | Arguments | Result |
summary | Produces a summary of the requested summary class | Name of summary class | Summary |
Expressions
Arithmetic expressions | |||
Name | Description | Arguments | Result |
---|---|---|---|
add | Add the arguments together | Numeric+ | Numeric |
+ | Add left and right argument | Numeric, Numeric | Numeric |
mul | Multiply the arguments together | Numeric+ | Numeric |
* | Multiply left and right argument | Numeric, Numeric | Numeric |
sub | Subtract second argument from first, third from result, etc | Numeric+ | Numeric |
- | Subtract right argument from left | Numeric, Numeric | Numeric |
div | Divide first argument by second, result by third, etc | Numeric+ | Numeric |
/ | Divide left argument by right | Numeric, Numeric | Numeric |
mod | Modulo first argument by second, result by third, etc | Numeric+ | Numeric |
% | Modulo left argument by right | Numeric, Numeric | Numeric |
neg | Negate argument | Numeric | Numeric |
- | Negate right argument | Numeric | Numeric |
Bitwise expressions | |||
Name | Description | Arguments | Result |
and | AND the arguments in order | Long+ | Long |
or | OR the arguments in order | Long+ | Long |
xor | XOR the arguments in order | Long+ | Long |
String expressions | |||
Name | Description | Arguments | Result |
strlen | Count the number of bytes in argument | String | Long |
strcat | Concatenate arguments in order | String+ | String |
Type conversion expressions | |||
Name | Description | Arguments | Result |
todouble | Convert argument to double | Any | Double |
tolong | Convert argument to long | Any | Long |
tostring | Convert argument to string | Any | String |
toraw | Convert argument to raw | Any | Raw |
Raw data expressions | |||
Name | Description | Arguments | Result |
cat | Cat the binary representation of the arguments together | Any+ | Raw |
md5 | Does an md5 over the binary representation of the argument, and keeps the lowest 'width' bits | Any, Numeric(width) | Raw |
xorbit | Does an xor of 'width' bits over the binary representation of the argument. Width is rounded up to a multiple of 8 | Any, Numeric(width) | Raw |
Accessor expressions | |||
Name | Description | Arguments | Result |
relevance | Return the computed rank of a document | None | Double |
docidnsspecific | Return the docid without namespace.
Applies only to streaming search
all( group(docidnsspecific()) each(output(count())) ) | None | String |
<attribute-name> | Return the value of the named attribute | None | Any |
array.at |
Array element access.
The expression array.at(myarray, idx) returns one value per document
by evaluating the idx expression and using it as an index into the array.
The expression can then be used to build bigger expressions such as
output(sum(array.at(myarray, 0)))
which will sum the first element in the array of each document.
| Array, Numeric | Any |
interpolatedlookup |
Counts elements in a sorted array that are less than an expression,
with linear interpolation if the expression is between element values.
The operation
When the lookup argument's value is between two consecutive array element values,
the returned position will be a linear interpolation between their respective indexes.
The return value is always in the range
Assume
| Array, Numeric | Numeric |
Bucket expressions | |||
Name | Description | Arguments | Result |
fixedwidth | Maps the value of the first argument into consecutive buckets whose width equals the second argument | Any, Numeric | NumericBucketList |
predefined | Maps the value of the first argument into the given buckets. Standard mathematical start and end specifiers may be used to define the width of a bucket. The "(" and ")" evaluates to "[" and ">" by default | Any, Bucket+ | BucketList |
Time expressionsUse the query parameter "timezone" to set the timezone to use when running these expressions. E.g.&timezone=GMT-1 . Refer to Sun's
TimeZone reference
| |||
Name | Description | Arguments | Result |
time.dayofmonth | Returns the day of month (1-31) for the given timestamp | Long | Long |
time.dayofweek | Returns the day of week (0-6) for the given timestamp, Monday being 0 | Long | Long |
time.dayofyear | Returns the day of year (0-365) for the given timestamp | Long | Long |
time.hourofday | Returns the hour of day (0-23) for the given timestamp | Long | Long |
time.minuteofhour | Returns the minute of hour (0-59) for the given timestamp | Long | Long |
time.monthofyear | Returns the month of year (1-12) for the given timestamp | Long | Long |
time.secondofminute | Returns the second of minute (0-59) for the given timestamp | Long | Long |
time.year | Returns the full year (e.g. 2009) of the given timestamp | Long | Long |
time.date | Returns the date (e.g. 2009-01-10) of the given timestamp | Long | Long |
List expressions | |||
Name | Description | Arguments | Result |
size | Return the number of elements in the argument if it is a list. If not return 1 | Any | Long |
sort | Sort the elements in argument in ascending order if argument is a list If not it is a NOP | Any | Any |
reverse | Reverse the elements in the argument if argument is a list If not it is a NOP | Any | Any |
Other expressions | |||
Name | Description | Arguments | Result |
zcurve.x |
Returns the X component of the given zcurve encoded 2d point.
All fields of type "position" have an accompanying "<fieldName>_zcurve" attribute
that can be decoded using this expression, e.g. zcurve.x(foo_zcurve)
| Long | Long |
zcurve.y | Returns the Y component of the given zcurve encoded 2d point | Long | Long |
uca |
Converts the attribute string using unicode collation algorithm.
Groups are sorted using locale aware sorting, with the default and primary strength values, respectively:
all( group(s) order(max(uca(s, "sv"))) each(output(count())) ) all( group(s) order(max(uca(s, "sv", "PRIMARY"))) each(output(count())) ) |
Any, Locale(String), Strength(String) | Raw |
Single argument standard mathematical expressionsThese are the standard mathematical functions as found in the Java Math class. | |||
Name | Description | Arguments | Result |
math.exp | Double | Double | |
math.log | Double | Double | |
math.log1p | Double | Double | |
math.log10 | Double | Double | |
math.sqrt | Double | Double | |
math.cbrt | Double | Double | |
math.sin | Double | Double | |
math.cos | Double | Double | |
math.tan | Double | Double | |
math.asin | Double | Double | |
math.acos | Double | Double | |
math.atan | Double | Double | |
math.sinh | Double | Double | |
math.cosh | Double | Double | |
math.tanh | Double | Double | |
math.asinh | Double | Double | |
math.acosh | Double | Double | |
math.atanh | Double | Double | |
Dual argument standard mathematical expressions | |||
Name | Description | Arguments | Result |
math.pow | Return X^Y. | Double, Double | Double |
math.hypot | Return length of hypotenuse given X and Y sqrt(X^2 + Y^2) | Double, Double | Double |
Select parameter language grammar
request ::= group [ "where" "(" ( "true" | "$query" ) ")" ] group ::= ( "all" | "each") "(" operations ")" [ "as" "(" identifier ")" ] operations ::= [ "group" "(" expression ")" ] ( ( "alias" "(" identifier "," expression ")" ) | ( "max" "(" number ")" ) | ( "order" "(" expList | aggrList ")" ) | ( "output" "(" aggrList ")" ) | ( "precision" "(" number ")" ) )* group* aggrList ::= aggr ( "," aggr )* aggr ::= ( ( "count" "(" ")" ) | ( "sum" "(" exp ")" ) | ( "avg" "(" exp ")" ) | ( "max" "(" exp ")" ) | ( "min" "(" exp ")" ) | ( "xor" "(" exp ")" ) | ( "stddev" "(" exp ")" ) | ( "summary" "(" [ identifier ] ")" ) ) [ "as" "(" identifier ")" ] expList ::= exp ( "," exp )* exp ::= ( "+" | "-") ( "$" identifier [ "=" math ] ) | ( math ) | ( aggr ) math ::= value [ ( "+" | "-" | "*" | "/" | "%" ) value ] value ::= ( "(" exp ")" ) | ( "add" "(" expList ")" ) | ( "and" "(" expList ")" ) | ( "cat" "(" expList ")" ) | ( "div" "(" expList ")" ) | ( "docidnsspecific" "(" ")" ) | ( "fixedwidth" "(" exp "," number ")" ) | ( "interpolatedlookup" "(" attributeName "," exp ")") | ( "math" "." ( ( "exp" | "log" | "log1p" | "log10" | "sqrt" | "cbrt" | "sin" | "cos" | "tan" | "asin" | "acos" | "atan" | "sinh" | "cosh" | "tanh" | "asinh" | "acosh" | "atanh" ) "(" exp ")" | ( "pow" | "hypot" ) "(" exp "," exp ")" )) | ( "max" "(" expList ")" ) | ( "md5" "(" exp "," number "," number ")" ) | ( "min" "(" expList ")" ) | ( "mod" "(" expList ")" ) | ( "mul" "(" expList ")" ) | ( "or" "(" expList ")" ) | ( "predefined" "(" exp "," "(" bucket ( "," bucket )* ")" ")" ) | ( "reverse" "(" exp ")" ) | ( "relevance" "(" ")" ) | ( "sort" "(" exp ")" ) | ( "strcat" "(" expList ")" ) | ( "strlen" "(" exp ")" ) | ( "size" "(" exp")" ) | ( "sub" "(" expList ")" ) | ( "time" "." ( "date" | "year" | "monthofyear" | "dayofmonth" | "dayofyear" | "dayofweek" | "hourofday" | "minuteofhour" | "secondofminute" ) "(" exp ")" ) | ( "todouble" "(" exp ")" ) | ( "tolong" "(" exp ")" ) | ( "tostring" "(" exp ")" ) | ( "toraw" "(" exp ")" ) | ( "uca" "(" exp "," string [ "," string ] ")" ) | ( "xor" "(" expList ")" ) | ( "xorbit" "(" exp "," number ")" ) | ( "zcurve" "." ( "x" | "y" ) "(" exp ")" ) | ( attributeName "." "at" "(" number ")") | ( attributeName ) bucket ::= "bucket" ( "(" | "[" | "<" ) ( "-inf" | rawvalue | number | string ) [ "," ( "inf" | rawvalue | number | string ) ] ( ")" | "]" | ">" ) rawvalue ::= "{" ( ( string | number ) "," )* "}"