# Grouping Reference

[](/en/reference/querying/grouping-language.html.md "View as Markdown") 

Read the [Vespa grouping guide](/en/querying/grouping.html) first, for examples and an introduction to grouping - this is the Vespa grouping reference.

Also note that using a [multivalued](/en/searching-multi-valued-fields.html) 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 or string constant (e.g., `group(1)` or `group("all")`) which makes one bucket with everything
- A document [attribute](../../content/attributes.html)
- A function over another expression (`xorbit`, `md5`, `cat`, `xor`, `and`, `or`, `add`, `sub`, `mul`, `div`, `mod`) or any other [expression](#expressions)
- The datatype of an expression is resolved using best-effort, similarly to how common programming languages do to resolve arithmetic of different data-typed operands 
- The results of any expression are either scalar or single-dimensional arrays 
  - `add(<array>)` adds all elements together to produce a scalar
  - `add(<arrayA>, <arrayB>)` adds each element together producing a new array whose size is `max(|<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)](#labels).

When grouping results, _groups_ that contain _outputs_, _group lists_ and _hit lists_ are generated. Group lists contain subgroups, 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](default-result-format.html).

### Multivalue attributes

A [multivalue](../../querying/searching-multivalue-fields) attribute is a [weighted set](../schemas/schemas.html#weightedset), [array](../schemas/schemas.html#array) or [map](../schemas/schemas.html#map). Most grouping functions will just handle the elements of multivalued attributes separately, as if they were all individual values in separate documents. If you are grouping over array of struct or maps, scoping will be used to preserve structure. Each entry in the array/map will be treated as a separate sub-document. The following syntax can be used when grouping on _map_ attribute fields.

Group on map keys:

```vespa-yql
all( group(mymap.key) each(output(count())) )
```

Group on map keys then on map values:

```vespa-yql
all( group(mymap.key) each( group(mymap.value) each(output(count())) ))
```

Group on values for key _my\_key_:

```vespa-yql
all( group(my_map{"my_key"}) each(output(count())) )
```

Group on struct field _my\_field_ referenced in map element _my\_key_:

```vespa-yql
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-valued and have the same data type as the key type of the map:

```vespa-yql
all( group(my_map{attribute(my_key_source)}) each(output(count())) )
```

Group on array of integers field:

```vespa-yql
all( group(my_array) each(output(count())) )
```

Group on struct field _my\_field_ in the _my\_array_ array of structs:

```vespa-yql
all( group(my_array.my_field) each(output(count())) )
```

[Tensors](../schemas/schemas.html#tensor) can not be used in grouping.

## Filtering groups

When grouping on multivalue attributes, it may be useful to filter the groups so that only some specific values are collected. This can be done by adding a filter. The `filter` clause expects a filter _predicate_:

- [regex("regular expression", input-expression)](#regex-filter)
- [range(min-limit, max-limit, input-expression)](#range-filter)
- [range(min-limit, max-limit, input-expression, bool, bool)](#range-filter)
- [istrue(input-expression)](#istrue-filter)
- [in(input-expression, "string", "string", ...)](#in-filter)
- [not _predicate_](#logical-predicates-filter)
- [_predicate_ and _predicate_](#logical-predicates-filter)
- [_predicate_ or _predicate_](#logical-predicates-filter)

When the `group` expression refers to a multivalue attribute, such as a field in an array of struct, the filter is evaluated once per element, and attributes from the same struct referenced in the filter are read from the same element. See the [array of struct example](../../querying/grouping.html#filtering-array-elements). For a single-valued `group` expression, the filter is evaluated once per hit, and a multivalue attribute in the filter matches if any of its values does.

### Regex filter

Use a regular expression to match the input, and include only documents that match in the grouping. The input will usually be the same -expression as in the "group" clause. Example:

```vespa-yql
all( group(my_array) filter(regex("foo.*", my_array)) ...)
```

Here only the values that start with a "foo" prefix in _my\_array_ are collected into groups, all others are ignored. See also [this example](../../querying/grouping.html#structured-grouping).

Regex filtering works on the string representation of any field type. For example, you can also filter on boolean values using regex(true) and regex(false).

The pattern can be passed as a query parameter instead of being written into the expression, see [parameter substitution](#parameter-substitution).

### Range filter

Use a `range` filter to match documents where a field value is between a lower and an upper bound. Example:

```vespa-yql
all( group(some_field) filter(range(1990, 2012, year)) ...)
```
Here, the lower bound is _inclusive_ (year ≥ 1990) and the upper bound is _exclusive_ (year \< 2012). Use optional bools at the end to control if the lower and upper bounds are inclusive, respectively. The first bool sets the lower bound inclusive, and the second sets the upper bound inclusive.
```vespa-yql
all( group(some_field) filter(range(1990, 2012, year, true, true)) ...)
```
Here, both lower and upper bounds are inclusive.
### IsTrue filter

Use `istrue` to filter using a boolean expression. The expression must evaluate to a boolean value, e.g. a boolean attribute. Example:

```vespa-yql
all( group(some_field) filter(istrue(my_bool_attribute)) ...)
```
Here, only documents where _my\_bool\_attribute_ evaluates to true are included in the grouping.
### In filter

Available since Vespa 8.757.45 .

Use `in` to allow only the hits where the input is equal to one of the given strings. The input expression is followed by one or more string constants. Example:

```vespa-yql
all( group(some_field) filter(in(category, "foo", "bar")) ...)
```
Here, only hits where _category_ is "foo" or "bar" are included in the grouping. If _category_ is a multivalue field, a hit is allowed if at least one of its values is equal to one of the strings. Unlike [regex](#regex-filter), the match is an exact comparison of the whole value, so "foo" does not match "foobar". Only string values are supported.
### Logical predicates

Use `not` to negate another filter expression. It takes a single sub-filter and matches when the sub-filter does not. Example:

```vespa-yql
all( group(my_field) filter( not regex("bar.*", my_other_field)) ...)
```
Use `or` to perform a logical disjunction across two sub-filters. The combined filter matches if any of the sub-filters evaluate to true. Example:
```vespa-yql
all( group(my_field) filter( regex("bar.*", my_field) or regex("baz.*", my_third_field) ) ...)
```
Use `and` to perform a logical conjunction across two sub-filters. The combined filter matches only if all of the sub-filters evaluate to true. Example:
```vespa-yql
all( group(my_field) filter( regex("bar.*", my_other_field) and regex("baz.*", my_third_field) ) ...)
```
These logical predicates can be nested to create complex filter conditions. Filter expressions follow _conventional precedence_ rules: `not` is evaluated before `and`, and `and` is evaluated before `or`. Operators of the same precedence are evaluated left-to-right. Use parentheses `(...)` to force a different grouping when needed. Example:
```vespa-yql
all(
    group(my_field)
    filter( (regex("bar.*", some_field) or regex("baz.*", other_field)) and not regex(".*foo", some_field))
    each(...)
)
```

## Order / max

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](#uca)

Limit the number of groups returned for each level using `max`, returning only first _n_ groups as specified by `order`:

- `order` changes the ordering of groups after a merge operation for the following aggregators: `count`, `avg` and ` sum`
- `order` **will not** change ordering of groups after a merge operation when `max` or `min` is used
- Default order, `-max(relevance())`, **does not** require use of [precision](#precision)

## Continuations

Pagination of grouping results is managed by `continuations`. These are opaque objects that can be combined and resubmitted 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 is 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](https://javadoc.io/doc/com.yahoo.vespa/container-search/latest/com/yahoo/search/grouping/Continuation.html) objects within [RootGroup](https://javadoc.io/doc/com.yahoo.vespa/container-search/latest/com/yahoo/search/grouping/result/RootGroup.html), [GroupList](https://javadoc.io/doc/com.yahoo.vespa/container-search/latest/com/yahoo/search/grouping/result/GroupList.html) and [HitList](https://javadoc.io/doc/com.yahoo.vespa/container-search/latest/com/yahoo/search/grouping/result/HitList.html) result objects. These can then be added back into the continuation list of the [GroupingRequest](https://javadoc.io/doc/com.yahoo.vespa/container-search/latest/com/yahoo/search/grouping/GroupingRequest.html) to paginate.

Refer to the [grouping guide](../../querying/grouping.html#pagination) 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 each clause will be identified by this label.

```vespa-yql
all(group(year) each(output(count())) as(by_year))
```

Individual output aggregators can also be assigned a label by adding `as(mylabel)` to the aggregator inside `output(...)`. This labels the aggregation result, not the group list.

```vespa-yql
all(group(author) output(count() as(authors_cardinality)))
```

## Aliases

Grouping expressions can be tagged with an _alias_. An alias allows the expression to be reused without having to repeat the expression verbatim.

```vespa-yql
all(group(a) alias(myalias, count()) each(output($myalias)))
```
 is equivalent to
```vespa-yql
all(group(a) each(output(count())))
```
.
```vespa-yql
all(group(a) order($myalias=count()) each(output($myalias)))
```
 is equivalent to
```vespa-yql
all(group(a) order(count()) each(output(count())))
```
.
## Precision

The number of intermediate groups returned from each content node during expression evaluation to give the container node more data to consider when selecting the groups that are to be evaluated further: `each(...) precision(1000)` A higher number costs more bandwidth, but leads to higher accuracy in some cases.

## Parameter substitution

Available since Vespa 8.774.9 .

As in [YQL](yql.html#parameter-substitution), a grouping expression can refer to a query parameter with `@name`. The reference is replaced by the value of the query parameter `name`. The value is used as-is and is never parsed as grouping syntax, so it needs no escaping and cannot change the structure of the expression. This makes it safe to pass user input to a grouping expression:

```
select=all( group(category) filter(in(category, @categories)) each(output(count())) )&categories=books,music
```

References can be used in the [select](../api/query.html#select) parameter, in the grouping expression after `|` in [YQL](yql.html#grouping), and in [select.grouping](../api/query.html#select.grouping). In `select.grouping`, the [JSON label field](json-query-language.html#grouping) can also be a reference: `"label": "@name"`.

Parameter names follow the same rules as in YQL: they start with a letter or underscore, followed by letters, digits, underscores or hyphens.

How the value is interpreted depends on where the reference is used:

- **Strings**: the pattern in `regex`, the label in `as`, and constants in expressions. The value is always a string, even when it looks like a number: with `label=42`, `group(@label)` is the same as `group("42")`, not `group(42)`.
- **Numbers**: the bounds of `range`, and the arguments of `accuracy`, `fixedwidth` and other functions that take a numeric constant. The value must be an integer or a decimal number, and may be negative.
- **Integers**: `max`, `precision`, and the number of bits in `md5` (1 to 128) and `xorbit` (1 to 64). The value must be an integer within the range the clause accepts. A decimal number such as `2.5` is rejected.
- **Lists**: a reference in `in(expression, @my_list)`. The value uses the same format as `in (@my_list)` in YQL: either `value, value, ...` with each value optionally quoted, or a JSON array. A single reference can therefore supply any number of values.

If a referenced parameter is not set, the query fails with the error `Input 'name' is not set`. References cannot be used for field names, function names or the bounds of `bucket`.

## Query parameters

The following _query parameters_ are relevant for grouping. See the [Query API Reference](../api/query.html#parameters) for description.

- [select](../api/query.html#select)
- [groupingSessionCache](../api/query.html#groupingsessioncache)
- [grouping.defaultMaxGroups](../api/query.html#grouping.defaultmaxgroups)
- [grouping.defaultMaxHits](../api/query.html#grouping.defaultmaxhits)
- [grouping.globalMaxGroups](../api/query.html#grouping.globalmaxgroups)
- [grouping.defaultPrecisionFactor](../api/query.html#grouping.defaultprecisionfactor)

## Grouping Session Cache

 **Important:** The grouping session cache is **only useful if** the grouping expression uses default ordering. The **drawback** is that when `max` is specified in the grouping expression, it might cause inaccuracies in aggregated values such as `count`. It is recommended to test whether this is an issue or not, and if so, adjust the `precision` parameter to still get correct counts.

The session cache stores intermediate grouping results in the content nodes when using multi-level grouping expressions, in order to speed up grouping at a potential loss of accuracy. This causes the query and grouping expression to be run only once.

When having multi-level grouping expressions, the search query is normally re-run for each level. The drawback of this is that, with an expensive ranking function, the query will take more time than strictly necessary.

## 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
- Multiple quantiles of an expressions value
- The value of an expression for the document with the smallest or largest value of another expression (argmin, argmax)

When all arguments are numeric, the result type is resolved by looking at the argument types. If all arguments are longs, the result is a long. If at least one argument is a double, the result is a double.

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 take 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.

Compute quantiles by listing the desired quantile values (comma-separated) in brackets, followed by a comma and the expression (e.g., a field):

```vespa-yql
all( group(city) each(output(quantiles([0.5], delivery_days) as(median_delivery_days) ) ) )
```
to compute the median, or
```vespa-yql
all( group(city) each(output(quantiles([0.5, 0.9], delivery_days))) )
```
This computes the median (p50) and 90th percentile (p90) time to delivery in days per city. Note that quantiles are computed using [KLL Sketch](https://datasketches.apache.org/docs/KLL/KLLSketch.html), so they are approximate.

Use `argmin(key, value)` and `argmax(key, value)` to get the value of one expression for the document that has the smallest or largest value of another expression:

```vespa-yql
all( group(artist) each(output(argmin(price, title))) )
```
This outputs the title of the cheapest track per artist, where `min(price)` would only output the price. The key must be numeric, while the value can be of any type, including multivalue. Documents where the key is not set are skipped, and the output is `null` if no document in the group has a key. If several documents share the smallest or largest key, one of them is selected. Both can be used in `order`, e.g. `order(-argmin(price, title))`. Available since Vespa 8.761.27 .

Multivalue fields, such as maps and 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:

```vespa-yql
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:

```vespa-yql
all( group("my_group") each(output(sum(mymap{"foo"}))) )
```

Refer to the system test for [grouping on struct and map types](https://github.com/vespa-engine/system-test/blob/master/tests/search/struct_and_map_types/struct_and_map_grouping.rb) 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 every time 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 |
| quantiles | Computes one or multiple quantiles of the values of an expression. Quantiles must be a number between 0 and 1 inclusive. | [Numeric+], Expr | [{"quantile":Double,"value":Double}+] |
| argmin | Keeps the value of the second argument for the document with the smallest value of the first argument | Numeric, Any | Any |
| argmax | Keeps the value of the second argument for the document with the largest value of the first argument | Numeric, Any | Any |
| 
### Hit aggregators
 |
| Name | Description | Arguments | Result |
| --- | --- | --- | --- |
| 

summary

 | Produces a summary of the requested [summary class](/en/reference/schemas/schemas.html#document-summary) | 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 |
| \<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. 
- The `idx` expression is capped to `[0, size(myarray)-1]`
- If \> array size, the last element is returned
- If \< 0, the first element is returned

 | 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 `interpolatedlookup(myarray, expr)` is intended for generic graph/function lookup. The data in `myarray` should be numerical values sorted in ascending order. The operation will then scan from the start of the array to find the position where the element values become equal to (or greater than) the value of the `expr` lookup argument, and return the index of that position.

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 `[0, size(myarray)-1]` of the valid index values for an array.

Assume `myarray` is a sorted array of type `array<double>` in each document: The expression `interpolatedlookup(myarray, 4.2)` is now a per-document expression that first evaluates the lookup argument, here a constant expression 4.2, and then looks at the contents of `myarray` in the document. The scan starts at the first element and proceeds until it hits an element value greater than 4.2 in the array. This means that:

- If the first element in the array is greater than 4.2, the expression returns 0
- If the first element in the array is exactly 4.2, the expression still returns 0
- If the first element in the array is 1.7 while the **second** element value is exactly 4.2, the expression returns 1.0 - the index of the second element
- If **all** the elements in the array are less than 4.2, the last valid array index `size(myarray)-1` is returned
- If the first 5 elements in the array have values smaller than the lookup argument, and the lookup argument is halfway between the fifth and sixth element, a value of 4.5 is returned - halfway between the array indexes of the fifth and sixth elements
- Similarly, if the elements in the array are `{0, 1, 2, 4, 8}` then passing a lookup argument of "5" would return 3.25 (linear interpolation between `indexOf(4)==3` and `indexOf(8)==4`)

 | 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.
- The buckets assume the type of the start/end specifiers (`string`, `long`, `double` or `raw`). Values are converted to this type before being compared with these specifiers. (e.g., `double` values are rounded to the nearest integer for buckets of type `long`).
- The end specifier can be skipped. The buckets `bucket(3)`/`bucket[3]` are the same as `bucket[3,4>`. This is allowed for string expressions as well; `bucket("c")` is identical to `bucket["c", "c ">`.
- The buckets split the value range into separate groups, so each value lands in at most one bucket. To find the bucket for each document quickly, Vespa expects the buckets in increasing order and without overlaps, and rejects a request where they are not. Neighboring buckets may share a boundary, as in `bucket(0,1000), bucket(1000,2000)`.

 | Any, Bucket+ | BucketList |
| 
### Time expressions
 The field must be a [long](../schemas/schemas.html#long), with second resolution (unix timestamp/epoch) - [examples](../../querying/grouping.html#time-and-date). Each of the time-functions will respect the [timezone](../api/query.html#timezone) query parameter. |
| 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 the argument in ascending order if the argument is a list. If not, it is a NOP | Any | Any |
| reverse | Reverse the elements in the argument if the 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](https://en.wikipedia.org/wiki/Z-order_curve) 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 |
| geo\_distance | 

Computes the great-circle distance from a [position](../schemas/schemas.html#position) field to a given point. The unit suffix `.km` or `.miles` selects the output unit. Works on both `position` and `array<position>` fields. For arrays, the minimum distance across all positions in the document is returned.

```vespa-yql
all( group(fixedwidth(geo_distance(attribute(location), 63.4, 10.4).km, 10)) each(output(count())) )
```

Available since Vespa 8.664.22 .

 | Attribute(position), Double(lat), Double(lng) | Double |
| uca | 

Converts the attribute string using [unicode collation algorithm](https://www.unicode.org/reports/tr10/). Groups are sorted using locale-aware sorting, with the default and primary strength values, respectively:

```vespa-yql
all( group(s) order(max(uca(s, "sv"))) each(output(count())) )
```

```vespa-yql
all( group(s) order(max(uca(s, "sv", "PRIMARY"))) each(output(count())) )
```
 | Any, Locale(String), Strength(String) | Raw |
| 
### Single argument standard mathematical expressions
 These are the standard mathematical functions as found in the Java [Math](https://docs.oracle.com/javase/8/docs/api/java/lang/Math.html) class. |
| Name | Description | Arguments | Result |
| --- | --- | --- | --- |
| math.exp | &nbsp; | Double | Double |
| math.log | &nbsp; | Double | Double |
| math.log1p | &nbsp; | Double | Double |
| math.log10 | &nbsp; | Double | Double |
| math.sqrt | &nbsp; | Double | Double |
| math.cbrt | &nbsp; | Double | Double |
| math.sin | &nbsp; | Double | Double |
| math.cos | &nbsp; | Double | Double |
| math.tan | &nbsp; | Double | Double |
| math.asin | &nbsp; | Double | Double |
| math.acos | &nbsp; | Double | Double |
| math.atan | &nbsp; | Double | Double |
| math.sinh | &nbsp; | Double | Double |
| math.cosh | &nbsp; | Double | Double |
| math.tanh | &nbsp; | Double | Double |
| math.asinh | &nbsp; | Double | Double |
| math.acosh | &nbsp; | Double | Double |
| math.atanh | &nbsp; | 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 |

## Filters

| 
### String filters
 |
| Name | Description | Arguments | Result |
| --- | --- | --- | --- |
| regex | Matches a field against a regular expression string. | String, Expression | Bool |
| in | Matches when the string value of an expression is equal to one of the given strings. | Expression, String, String... | Bool |
| 
### Numeric filters
 |
| Name | Description | Arguments | Result |
| --- | --- | --- | --- |
| range | Matches when a field is between a lower and upper bound. | Numeric, Numeric, Expression, Bool?, Bool? | Bool |
| 
### Boolean filters
 |
| Name | Description | Arguments | Result |
| --- | --- | --- | --- |
| istrue | Matches when a boolean expression evaluates to true. | Expression | Bool |
| 
### Predicate filters
 |
| Name | Description | Arguments | Result |
| --- | --- | --- | --- |
| and | Logical `and` between the arguments. | Filter, Filter | Bool |
| not | Logical `not` on the argument. | Filter | Bool |
| or | Logical `or` between the arguments. | Filter, Filter | Bool |

## Grouping language grammar

```
request ::= "all(" operations ")"
group ::= ( "all" | "each") "(" operations ")" ["as" "(" identifier ")"]
operations ::= ["group" "(" exp ")"]
               ( ( "alias" "(" identifier "," exp ")" ) |
                 ( filter ) |
                 ( "max" "(" ( number | "inf" ) ")" ) |
                 ( "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 ")" ) |
                 ( "quantiles" "(" "[" number ( "," number )* "]" "," exp ")" ) |
                 ( "argmin" "(" exp "," exp ")" ) |
                 ( "argmax" "(" exp "," exp ")" ) |
                 ( "summary" "(" [identifier] ")" ) )
               ["as" "(" identifier ")"]
expList ::= exp ( "," exp )*
exp ::= ( "+" | "-") ( "$" identifier ["=" math] ) | ( math ) | ( aggr )
filter ::= ( "filter" | "keep" ) "(" filterExp ")"
filterExp ::= filterAnd ( "or" filterAnd )*
filterAnd ::= filterNot ( "and" filterNot )*
filterNot ::= "not" filterNot | filterPrim
filterPrim ::= ( "(" filterExp ")" ) |
               ( "regex" "(" string "," exp ")" ) |
               ( "range" "(" number "," number "," exp ["," boolean "," boolean] ")" ) |
               ( "istrue" "(" exp ")" ) |
               ( "in" "(" exp ( "," string )+ ")" )
math ::= value [( "+" | "-" | "*" | "/" | "%" ) value]
value ::= ( "(" exp ")" ) |
               ( "add" "(" expList ")" ) |
               ( "and" "(" expList ")" ) |
               ( "cat" "(" expList ")" ) |
               ( "div" "(" expList ")" ) |
               ( "docidnsspecific" "(" ")" ) |
               ( "fixedwidth" "(" exp "," number ")" ) |
               ( "geo_distance" "(" "attribute" "(" attributeName ")" "," number "," number ")" "." ( "km" | "miles" ) ) |
               ( "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 ) "," )* "}"
```

 Copyright © 2026 - [Cookie Preferences](#)

### On this page:

- [Grouping Reference](#page-title)
- [Group](#group)
- [Multivalue attributes](#multivalue-attributes)
- [Filtering groups](#filtering-groups)
- [Regex filter](#regex-filter)
- [Range filter](#range-filter)
- [IsTrue filter](#istrue-filter)
- [In filter](#in-filter)
- [Logical predicates](#logical-predicates-filter)
- [Order / max](#order)
- [Continuations](#continuations)
- [Labels](#labels)
- [Aliases](#aliases)
- [Precision](#precision)
- [Parameter substitution](#parameter-substitution)
- [Query parameters](#query-parameters)
- [Grouping Session Cache](#grouping-session-cache)
- [Aggregators](#aggregators)
- [Group list aggregators](#group-list-aggregators)
- [Group aggregators](#group-aggregators)
- [Hit aggregators](#hit-aggregators)
- [Expressions](#expressions)
- [Arithmetic expressions](#arithmetic-expressions)
- [Bitwise expressions](#bitwise-expressions)
- [String expressions](#string-expressions)
- [Type conversion expressions](#type-conversion-expressions)
- [Raw data expressions](#raw-data-expressions)
- [Accessor expressions](#accessor-expressions)
- [Bucket expressions](#bucket-expressions)
- [Time expressions](#time-expressions)
- [List expressions](#list-expressions)
- [Other expressions](#other-expressions)
- [Single argument standard mathematical expressions](#single-argument-standard-mathematical-expressions)
- [Dual argument standard mathematical expressions](#dual-argument-standard-mathematical-expressions)
- [Filters](#filters)
- [String filters](#string-filters)
- [Numeric filters](#numeric-filters)
- [Boolean filters](#boolean-filters)
- [Predicate filters](#predicate-filters)
- [Grouping language grammar](#grouping-language-grammar)

