io.lettuce.core.search.arguments

Class AggregateArgs.CollectReducer

java.lang.Object

io.lettuce.core.search.arguments.AggregateArgs.Reducer

io.lettuce.core.search.arguments.AggregateArgs.CollectReducer

Enclosing class:

AggregateArgs

@Experimental
public static class AggregateArgs.CollectReducer
extends AggregateArgs.Reducer

Represents a REDUCE COLLECT clause in an aggregation pipeline.

Within each GROUPBY group, COLLECT projects a chosen set of fields from every row and returns them as an array of per-entry maps under the reducer alias, optionally sorted and bounded. It targets grouped-reporting workflows where the caller needs the representative rows of each group in a single aggregation query. The grammar produced by this builder is:

 
 REDUCE COLLECT <narg>
     FIELDS ( * | <num_fields> <@field> [<@field> ...] )
     [SORTBY <narg> <@field> [ASC|DESC] [<@field> [ASC|DESC] ...]]
     [LIMIT <offset> <count>]
   [AS <alias>]
 
 

Field and sort-key names are referenced with an @ prefix on the wire (the builder adds it automatically when it is missing). The output map keys are the bare names. FIELDS * projects whatever the pipeline has materialized at the COLLECT stage; it does not implicitly fetch the full document.

The collected column is a FieldValue of kind FieldValue.Kind.ARRAY with one element per collected entry; read the entries via asList() and each entry via asMap(), which normalizes the protocol-specific entry shape (RESP3 returns each entry as a map, RESP2 as a flat key/value array).

The number of collected entries per group is always bounded by the server: SORTBY without an explicit LIMIT returns at most 10 entries per group, and without either clause collection is capped by the search-max-aggregate-results configuration. Supply an explicit limit(...) to control the bound.

Experimental. Both the underlying Redis Search feature and this API may change. COLLECT is gated behind search-enable-unstable-features; enable it on the server before issuing aggregations that use this reducer.

Since:

7.8

See Also:

AggregateArgs.Reducer.collect()

Method Summary

Modifier and Type	Method and Description
AggregateArgs.CollectReducer	as(String alias)
void	build(CommandArgs<?,?> args)
AggregateArgs.CollectReducer	fields(String... fields) Project the named fields for every document in the group.
AggregateArgs.CollectReducer	fieldsAll() Project every field present in the pipeline at the COLLECT stage (FIELDS *).
AggregateArgs.CollectReducer	limit(long count) Bound the output per group to the first count entries (offset 0).
AggregateArgs.CollectReducer	limit(long offset, long count) Bound the output per group to count entries starting at offset.
AggregateArgs.CollectReducer	sortBy(AggregateArgs.SortProperty... properties) In-group sort by one or more properties.
AggregateArgs.CollectReducer	sortByAsc(String field) Convenience for sortBy(new SortProperty(field, SortDirection.ASC)).
AggregateArgs.CollectReducer	sortByDesc(String field) Convenience for sortBy(new SortProperty(field, SortDirection.DESC)).

Methods inherited from class io.lettuce.core.search.arguments.AggregateArgs.Reducer

avg, collect, count, countDistinct, max, min, sum

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

fields

public AggregateArgs.CollectReducer fields(String... fields)

Project the named fields for every document in the group. Names may be supplied with or without a leading @; the builder normalizes each to a single @<name> on the wire. Use @__key or ordinary document field names.

Mutually exclusive with fieldsAll(). May be called multiple times to append further fields.

Parameters:

fields - the fields to project

Returns:

this for chaining

Throws:

IllegalStateException - if fieldsAll() was already requested

Since:

7.8

fieldsAll

public AggregateArgs.CollectReducer fieldsAll()

Project every field present in the pipeline at the COLLECT stage (FIELDS *).

Per the COLLECT specification, * does not trigger an implicit load — fields must already be in the pipeline (typically via LOAD * or because they are grouping keys / reducer aliases). Mutually exclusive with fields(String[]).

Returns:

this for chaining

Throws:

IllegalStateException - if explicit fields were already added via fields(String[])

Since:

7.8

sortBy

public AggregateArgs.CollectReducer sortBy(AggregateArgs.SortProperty... properties)

In-group sort by one or more properties. May be called multiple times to append further sort keys.

Note: when SORTBY is supplied without an explicit limit(...), the server applies a default limit of 10 entries per group. Supply an explicit limit to collect more sorted entries. Without SORTBY, entry order is unspecified and collection is capped by the server's search-max-aggregate-results configuration.

Parameters:

properties - the sort properties

Returns:

this for chaining

Since:

7.8

sortByAsc

public AggregateArgs.CollectReducer sortByAsc(String field)

Convenience for sortBy(new SortProperty(field, SortDirection.ASC)).

Parameters:

field - the field to sort by ascending

Returns:

this for chaining

Since:

7.8

sortByDesc

public AggregateArgs.CollectReducer sortByDesc(String field)

Convenience for sortBy(new SortProperty(field, SortDirection.DESC)).

Parameters:

field - the field to sort by descending

Returns:

this for chaining

Since:

7.8

limit

public AggregateArgs.CollectReducer limit(long count)

Bound the output per group to the first count entries (offset 0).

Parameters:

count - the maximum number of entries per group

Returns:

this for chaining

Throws:

IllegalArgumentException - if count is negative

Since:

7.8

limit

public AggregateArgs.CollectReducer limit(long offset,
                                          long count)

Bound the output per group to count entries starting at offset.

Parameters:

offset - the number of entries to skip

count - the maximum number of entries to return

Returns:

this for chaining

Throws:

IllegalArgumentException - if offset or count is negative

Since:

7.8

as

public AggregateArgs.CollectReducer as(String alias)

Overrides:

as in class AggregateArgs.Reducer

build

public void build(CommandArgs<?,?> args)

Overrides:

build in class AggregateArgs.Reducer