Package org.springframework.data.mongodb.core.aggregation

Class Aggregation

java.lang.Object

org.springframework.data.mongodb.core.aggregation.Aggregation

Direct Known Subclasses:

AggregationUpdate, TypedAggregation

public class Aggregation
extends Object

An Aggregation is a representation of a list of aggregation steps to be performed by the MongoDB Aggregation Framework.

Since:

1.3

Author:

Tobias Trelle, Thomas Darimont, Oliver Gierke, Mark Paluch, Alessio Fachechi, Christoph Strobl, Nikolay Bogdanov, Gustavo de Geus, Jérôme Guyon, Sangyong Choi

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CURRENT	References the start of the field path being processed in the aggregation pipeline stage.
static final AggregationOperationContext	DEFAULT_CONTEXT
static final AggregationOptions	DEFAULT_OPTIONS
protected final AggregationPipeline	pipeline
static final String	REMOVE	A variable to conditionally exclude a field.
static final String	ROOT	References the root document, i.e. the top-level document, currently being processed in the aggregation pipeline stage.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Aggregation(List<AggregationOperation> aggregationOperations)	Creates a new Aggregation from the given AggregationOperations.
protected	Aggregation(List<AggregationOperation> aggregationOperations, AggregationOptions options)	Creates a new Aggregation from the given AggregationOperations.
protected	Aggregation(AggregationOperation... aggregationOperations)	Creates a new Aggregation from the given AggregationOperations.

Method Summary

Modifier and Type	Method	Description
static AddFieldsOperation.AddFieldsOperationBuilder	addFields()	Obtain an builder instance to create a new AddFieldsOperation.
protected static List<AggregationOperation>	asAggregationList(AggregationOperation... aggregationOperations)
static Fields	bind(String name, String target)	Creates a new Fields instance from the given field name and target reference.
static BucketOperation	bucket(String groupByField)	Creates a new BucketOperation given groupByField.
static BucketOperation	bucket(AggregationExpression groupByExpression)	Creates a new BucketOperation given group-by expression.
static BucketAutoOperation	bucketAuto(String groupByField, int buckets)	Creates a new BucketAutoOperation given groupByField.
static BucketAutoOperation	bucketAuto(AggregationExpression groupByExpression, int buckets)	Creates a new BucketAutoOperation given group-by expression.
static CountOperation.CountOperationBuilder	count()	Creates a new CountOperation.CountOperationBuilder.
static FacetOperation	facet()	Creates a new FacetOperation.
static FacetOperation.FacetOperationBuilder	facet(AggregationOperation... aggregationOperations)	Creates a new FacetOperation.FacetOperationBuilder given Aggregation.
static Fields	fields(String... fields)	Creates a new Fields instance for the given field names.
static GeoNearOperation	geoNear(NearQuery query, String distanceField)	Creates a new GeoNearOperation instance from the given NearQuery and the distanceField.
AggregationOptions	getOptions()	Get the AggregationOptions.
AggregationPipeline	getPipeline()
static GraphLookupOperation.StartWithBuilder	graphLookup(String fromCollection)	Creates a new GraphLookupOperation.GraphLookupOperationFromBuilder to construct a GraphLookupOperation given fromCollection.
static GroupOperation	group(String... fields)	Creates a new GroupOperation for the given fields.
static GroupOperation	group(Fields fields)	Creates a new GroupOperation for the given Fields.
static LimitOperation	limit(long maxElements)	Creates a new LimitOperation limiting the result to the given number of elements.
static LookupOperation.LookupOperationBuilder	lookup()	Entrypoint for creating $lookup using a fluent builder API.
static LookupOperation	lookup(String from, String localField, String foreignField, String as)	Creates a new LookupOperation.
static LookupOperation	lookup(Field from, Field localField, Field foreignField, Field as)	Creates a new LookupOperation for the given Fields.
static MatchOperation	match(AggregationExpression expression)	Creates a new MatchOperation using the given AggregationExpression.
static MatchOperation	match(Criteria criteria)	Creates a new MatchOperation using the given Criteria.
static MatchOperation	match(CriteriaDefinition criteria)	Creates a new MatchOperation using the given CriteriaDefinition.
static MergeOperation.MergeOperationBuilder	merge()	Obtain a builder instance to create a new MergeOperation.
static <T> TypedAggregation<T>	newAggregation(Class<T> type, List<? extends AggregationOperation> operations)	Creates a new TypedAggregation for the given type and AggregationOperations.
static <T> TypedAggregation<T>	newAggregation(Class<T> type, AggregationOperation... operations)	Creates a new TypedAggregation for the given type and AggregationOperations.
static Aggregation	newAggregation(List<? extends AggregationOperation> operations)	Creates a new Aggregation from the given AggregationOperations.
static Aggregation	newAggregation(AggregationOperation... operations)	Creates a new Aggregation from the given AggregationOperations.
static AggregationOptions.Builder	newAggregationOptions()	Returns a new AggregationOptions.Builder.
static AggregationUpdate	newUpdate(AggregationOperation... operations)	Creates a new AggregationUpdate from the given AggregationOperations.
static OutOperation	out(String outCollectionName)	Creates a new OutOperation using the given collection name.
static String	previousOperation()	A pointer to the previous AggregationOperation.
static ProjectionOperation	project(Class<?> type)	Creates a new ProjectionOperation including all top level fields of the given given Class.
static ProjectionOperation	project(String... fields)	Creates a new ProjectionOperation including the given fields.
static ProjectionOperation	project(Fields fields)	Creates a new ProjectionOperation including the given Fields.
static RedactOperation	redact(AggregationExpression condition)	Creates a new RedactOperation that can restrict the content of a document based on information stored within the document itself.
static ReplaceRootOperation.ReplaceRootOperationBuilder	replaceRoot()	Factory method to create a new ReplaceRootOperation.ReplaceRootDocumentOperationBuilder to configure a ReplaceRootOperation.
static ReplaceRootOperation	replaceRoot(String fieldName)	Factory method to create a new ReplaceRootOperation for the field with the given name.
static ReplaceRootOperation	replaceRoot(AggregationExpression aggregationExpression)	Factory method to create a new ReplaceRootOperation for the field with the given AggregationExpression.
static SampleOperation	sample(long sampleSize)	Creates a new SampleOperation to select the specified number of documents from its input randomly.
static SkipOperation	skip(long elementsToSkip)	Creates a new SkipOperation skipping the given number of elements.
static SortOperation	sort(Sort sort)	Factory method to create a new SortOperation for the given Sort.
static SortOperation	sort(Sort.Direction direction, String... fields)	Factory method to create a new SortOperation for the given sort Sort.Direction and fields.
static SortByCountOperation	sortByCount(String field)	Creates a new SortByCountOperation given groupByField.
static SortByCountOperation	sortByCount(AggregationExpression groupAndSortExpression)	Creates a new SortByCountOperation given group and sort expression.
static AggregationOperation	stage(String json)	Creates a new AggregationOperation taking the given json value as is.
static AggregationOperation	stage(org.bson.conversions.Bson aggregationOperation)	Creates a new AggregationOperation taking the given bson value as is.
org.bson.Document	toDocument(String inputCollectionName, AggregationOperationContext rootContext)	Converts this Aggregation specification to a Document.
List<org.bson.Document>	toPipeline(AggregationOperationContext rootContext)	Renders this Aggregation specification to an aggregation pipeline returning a List of Document.
String	toString()
static UnwindOperation	unwind(String field)	Factory method to create a new UnwindOperation for the field with the given name.
static UnwindOperation	unwind(String field, boolean preserveNullAndEmptyArrays)	Factory method to create a new UnwindOperation for the field with the given name and preserveNullAndEmptyArrays.
static UnwindOperation	unwind(String field, String arrayIndex)	Factory method to create a new UnwindOperation for the field with the given name including the name of a new field to hold the array index of the element as arrayIndex.
static UnwindOperation	unwind(String field, String arrayIndex, boolean preserveNullAndEmptyArrays)	Factory method to create a new UnwindOperation for the field with the given name, including the name of a new field to hold the array index of the element as arrayIndex using preserveNullAndEmptyArrays.
static VectorSearchOperation.PathContributor	vectorSearch(String indexName)	Creates a new VectorSearchOperation by starting from the indexName to use.
Aggregation	withOptions(AggregationOptions options)	Returns a copy of this Aggregation with the given AggregationOptions set.

Methods inherited from class java.lang.Object

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

Field Details

ROOT

public static final String ROOT

References the root document, i.e. the top-level document, currently being processed in the aggregation pipeline stage.

CURRENT

public static final String CURRENT

References the start of the field path being processed in the aggregation pipeline stage. Unless documented otherwise, all stages start with CURRENT the same as ROOT.

REMOVE

public static final String REMOVE

A variable to conditionally exclude a field. In a $projection, a field set to the variable REMOVE is excluded from the output.

 

 db.books.aggregate( [
 {
     $project: {
         title: 1,
         "author.first": 1,
         "author.last" : 1,
         "author.middle": {
             $cond: {
                 if: { $eq: [ "", "$author.middle" ] },
                 then: "$$REMOVE",
                 else: "$author.middle"
             }
         }
     }
 } ] )
 
 

DEFAULT_CONTEXT

public static final AggregationOperationContext DEFAULT_CONTEXT

DEFAULT_OPTIONS

public static final AggregationOptions DEFAULT_OPTIONS

pipeline

protected final AggregationPipeline pipeline

Constructor Details

Aggregation

protected Aggregation(AggregationOperation... aggregationOperations)

Creates a new Aggregation from the given AggregationOperations.

Parameters:

aggregationOperations - must not be null or empty.

Aggregation

protected Aggregation(List<AggregationOperation> aggregationOperations)

Creates a new Aggregation from the given AggregationOperations.

Parameters:

aggregationOperations - must not be null or empty.

Aggregation

protected Aggregation(List<AggregationOperation> aggregationOperations,
 AggregationOptions options)

Creates a new Aggregation from the given AggregationOperations.

Parameters:

aggregationOperations - must not be null.

options - must not be null or empty.

Method Details

newAggregation

public static Aggregation newAggregation(List<? extends AggregationOperation> operations)

Creates a new Aggregation from the given AggregationOperations.

Parameters:

operations - must not be null or empty.

newAggregation

public static Aggregation newAggregation(AggregationOperation... operations)

Creates a new Aggregation from the given AggregationOperations.

Parameters:

operations - must not be null or empty.

newUpdate

public static AggregationUpdate newUpdate(AggregationOperation... operations)

Creates a new AggregationUpdate from the given AggregationOperations.

Parameters:

operations - can be empty but must not be null.

Returns:

new instance of AggregationUpdate.

Since:

3.0

withOptions

public Aggregation withOptions(AggregationOptions options)

Returns a copy of this Aggregation with the given AggregationOptions set. Note that options are supported in MongoDB version 2.6+.

Parameters:

options - must not be null.

Returns:

new instance of Aggregation.

Since:

1.6

newAggregation

public static <T> TypedAggregation<T> newAggregation(Class<T> type,
 List<? extends AggregationOperation> operations)

Creates a new TypedAggregation for the given type and AggregationOperations.

Parameters:

type - must not be null.

operations - must not be null or empty.

newAggregation

public static <T> TypedAggregation<T> newAggregation(Class<T> type,
 AggregationOperation... operations)

Creates a new TypedAggregation for the given type and AggregationOperations.

Parameters:

type - must not be null.

operations - must not be null or empty.

asAggregationList

protected static List<AggregationOperation> asAggregationList(AggregationOperation... aggregationOperations)

Parameters:

aggregationOperations - must not be null or empty.

Returns:

getOptions

public AggregationOptions getOptions()

Get the AggregationOptions.

Returns:

never null.

Since:

2.1

previousOperation

public static String previousOperation()

A pointer to the previous AggregationOperation.

Returns:

addFields

public static AddFieldsOperation.AddFieldsOperationBuilder addFields()

Obtain an builder instance to create a new AddFieldsOperation.
Starting in version 4.2, MongoDB adds a new aggregation pipeline stage $set that is an alias for $addFields.

Returns:

new instance of AddFieldsOperation.AddFieldsOperationBuilder.

Since:

3.0

See Also:

• AddFieldsOperation

stage

public static AggregationOperation stage(org.bson.conversions.Bson aggregationOperation)

Creates a new AggregationOperation taking the given bson value as is.

 Aggregation.stage(Aggregates.search(exists(fieldPath("..."))));
 

Field mapping against a potential domain type or previous aggregation stages will not happen.

Parameters:

aggregationOperation - the must not be null.

Returns:

new instance of AggregationOperation.

Since:

4.0

stage

public static AggregationOperation stage(String json)

Creates a new AggregationOperation taking the given json value as is.

 Aggregation.stage("{ $search : { near : { path : 'released' , origin : ... } } }");
 

Field mapping against a potential domain type or previous aggregation stages will not happen.

Parameters:

json - the JSON representation of the pipeline stage. Must not be null.

Returns:

new instance of AggregationOperation.

Since:

4.0

project

public static ProjectionOperation project(String... fields)

Creates a new ProjectionOperation including the given fields.

Parameters:

fields - must not be null.

Returns:

new instance of ProjectionOperation.

project

public static ProjectionOperation project(Fields fields)

Creates a new ProjectionOperation including the given Fields.

Parameters:

fields - must not be null.

Returns:

new instance of ProjectionOperation.

project

public static ProjectionOperation project(Class<?> type)

Creates a new ProjectionOperation including all top level fields of the given given Class.

Parameters:

type - must not be null.

Returns:

new instance of ProjectionOperation.

Since:

2.2

unwind

public static UnwindOperation unwind(String field)

Factory method to create a new UnwindOperation for the field with the given name.

Parameters:

field - must not be null or empty.

Returns:

new instance of UnwindOperation.

replaceRoot

public static ReplaceRootOperation replaceRoot(String fieldName)

Factory method to create a new ReplaceRootOperation for the field with the given name.

Parameters:

fieldName - must not be null or empty.

Returns:

new instance of ReplaceRootOperation.

Since:

1.10

replaceRoot

public static ReplaceRootOperation replaceRoot(AggregationExpression aggregationExpression)

Factory method to create a new ReplaceRootOperation for the field with the given AggregationExpression.

Parameters:

aggregationExpression - must not be null.

Returns:

new instance of ReplaceRootOperation.

Since:

1.10

replaceRoot

public static ReplaceRootOperation.ReplaceRootOperationBuilder replaceRoot()

Factory method to create a new ReplaceRootOperation.ReplaceRootDocumentOperationBuilder to configure a ReplaceRootOperation.

Returns:

the ReplaceRootDocumentOperationBuilder.

Since:

1.10

unwind

public static UnwindOperation unwind(String field,
 boolean preserveNullAndEmptyArrays)

Factory method to create a new UnwindOperation for the field with the given name and preserveNullAndEmptyArrays. Note that extended unwind is supported in MongoDB version 3.2+.

Parameters:

field - must not be null or empty.

preserveNullAndEmptyArrays - true to output the document if path is null, missing or array is empty.

Returns:

new UnwindOperation

Since:

1.10

unwind

public static UnwindOperation unwind(String field,
 String arrayIndex)

Factory method to create a new UnwindOperation for the field with the given name including the name of a new field to hold the array index of the element as arrayIndex. Note that extended unwind is supported in MongoDB version 3.2+.

Parameters:

field - must not be null or empty.

arrayIndex - must not be null or empty.

Returns:

new UnwindOperation

Since:

1.10

unwind

public static UnwindOperation unwind(String field,
 String arrayIndex,
 boolean preserveNullAndEmptyArrays)

Factory method to create a new UnwindOperation for the field with the given name, including the name of a new field to hold the array index of the element as arrayIndex using preserveNullAndEmptyArrays. Note that extended unwind is supported in MongoDB version 3.2+.

Parameters:

field - must not be null or empty.

arrayIndex - must not be null or empty.

preserveNullAndEmptyArrays - true to output the document if path is null, missing or array is empty.

Returns:

new UnwindOperation

Since:

1.10

group

public static GroupOperation group(String... fields)

Creates a new GroupOperation for the given fields.

Parameters:

fields - must not be null.

Returns:

new instance of GroupOperation.

group

public static GroupOperation group(Fields fields)

Creates a new GroupOperation for the given Fields.

Parameters:

fields - must not be null.

Returns:

graphLookup

public static GraphLookupOperation.StartWithBuilder graphLookup(String fromCollection)

Creates a new GraphLookupOperation.GraphLookupOperationFromBuilder to construct a GraphLookupOperation given fromCollection.

Parameters:

fromCollection - must not be null or empty.

Returns:

new instance of GraphLookupOperation.StartWithBuilder for creating a GraphLookupOperation.

Since:

1.10

vectorSearch

public static VectorSearchOperation.PathContributor vectorSearch(String indexName)

Creates a new VectorSearchOperation by starting from the indexName to use.

Parameters:

indexName - must not be null or empty.

Returns:

new instance of VectorSearchOperation.PathContributor.

Since:

4.5

sort

public static SortOperation sort(Sort sort)

Factory method to create a new SortOperation for the given Sort.

Parameters:

sort - must not be null.

Returns:

new instance of SortOperation.

sort

public static SortOperation sort(Sort.Direction direction,
 String... fields)

Factory method to create a new SortOperation for the given sort Sort.Direction and fields.

Parameters:

direction - must not be null.

fields - must not be null.

Returns:

new instance of SortOperation.

sortByCount

public static SortByCountOperation sortByCount(String field)

Creates a new SortByCountOperation given groupByField.

Parameters:

field - must not be null or empty.

Returns:

new instance of SortByCountOperation.

Since:

2.1

sortByCount

public static SortByCountOperation sortByCount(AggregationExpression groupAndSortExpression)

Creates a new SortByCountOperation given group and sort expression.

Parameters:

groupAndSortExpression - must not be null.

Returns:

new instance of SortByCountOperation.

Since:

2.1

skip

public static SkipOperation skip(long elementsToSkip)

Creates a new SkipOperation skipping the given number of elements.

Parameters:

elementsToSkip - must not be less than zero.

Returns:

new instance of SkipOperation.

limit

public static LimitOperation limit(long maxElements)

Creates a new LimitOperation limiting the result to the given number of elements.

Parameters:

maxElements - must not be less than zero.

Returns:

new instance of LimitOperation.

sample

public static SampleOperation sample(long sampleSize)

Creates a new SampleOperation to select the specified number of documents from its input randomly.

Parameters:

sampleSize - must not be less than zero.

Returns:

new instance of SampleOperation.

Since:

2.0

match

public static MatchOperation match(Criteria criteria)

Creates a new MatchOperation using the given Criteria.

Parameters:

criteria - must not be null.

Returns:

new instance of MatchOperation.

match

public static MatchOperation match(CriteriaDefinition criteria)

Creates a new MatchOperation using the given CriteriaDefinition.

Parameters:

criteria - must not be null.

Returns:

new instance of MatchOperation.

Since:

1.10

match

public static MatchOperation match(AggregationExpression expression)

Creates a new MatchOperation using the given AggregationExpression.

Parameters:

expression - must not be null.

Returns:

new instance of MatchOperation.

Since:

3.3

geoNear

public static GeoNearOperation geoNear(NearQuery query,
 String distanceField)

Creates a new GeoNearOperation instance from the given NearQuery and the distanceField. The distanceField defines output field that contains the calculated distance.

Parameters:

query - must not be null.

distanceField - must not be null or empty.

Returns:

new instance of GeoNearOperation.

Since:

1.7

merge

public static MergeOperation.MergeOperationBuilder merge()

Obtain a builder instance to create a new MergeOperation.

Returns:

new instance of MergeOperation.MergeOperationBuilder.

Since:

3.0

See Also:

• MergeOperation

out

public static OutOperation out(String outCollectionName)

Creates a new OutOperation using the given collection name. This operation must be the last operation in the pipeline.

Parameters:

outCollectionName - collection name to export aggregation results. The OutOperation creates a new collection in the current database if one does not already exist. The collection is not visible until the aggregation completes. If the aggregation fails, MongoDB does not create the collection. Must not be null.

Returns:

new instance of OutOperation.

bucket

public static BucketOperation bucket(String groupByField)

Creates a new BucketOperation given groupByField.

Parameters:

groupByField - must not be null or empty.

Returns:

new instance of BucketOperation.

Since:

1.10

bucket

public static BucketOperation bucket(AggregationExpression groupByExpression)

Creates a new BucketOperation given group-by expression.

Parameters:

groupByExpression - must not be null.

Returns:

new instance of BucketOperation.

Since:

1.10

bucketAuto

public static BucketAutoOperation bucketAuto(String groupByField,
 int buckets)

Creates a new BucketAutoOperation given groupByField.

Parameters:

groupByField - must not be null or empty.

buckets - number of buckets, must be a positive integer.

Returns:

new instance of BucketAutoOperation.

Since:

1.10

bucketAuto

public static BucketAutoOperation bucketAuto(AggregationExpression groupByExpression,
 int buckets)

Creates a new BucketAutoOperation given group-by expression.

Parameters:

groupByExpression - must not be null.

buckets - number of buckets, must be a positive integer.

Returns:

new instance of BucketAutoOperation.

Since:

1.10

facet

public static FacetOperation facet()

Creates a new FacetOperation.

Returns:

new instance of FacetOperation.

Since:

1.10

facet

public static FacetOperation.FacetOperationBuilder facet(AggregationOperation... aggregationOperations)

Creates a new FacetOperation.FacetOperationBuilder given Aggregation.

Parameters:

aggregationOperations - the sub-pipeline, must not be null.

Returns:

new instance of FacetOperation.

Since:

1.10

lookup

public static LookupOperation lookup(String from,
 String localField,
 String foreignField,
 String as)

Creates a new LookupOperation.

Parameters:

from - must not be null.

localField - must not be null.

foreignField - must not be null.

as - must not be null.

Returns:

never null.

Since:

1.9

lookup

public static LookupOperation lookup(Field from,
 Field localField,
 Field foreignField,
 Field as)

Creates a new LookupOperation for the given Fields.

Parameters:

from - must not be null.

localField - must not be null.

foreignField - must not be null.

as - must not be null.

Returns:

never null.

Since:

1.9

lookup

public static LookupOperation.LookupOperationBuilder lookup()

Entrypoint for creating $lookup using a fluent builder API.

 Aggregation.lookup().from("restaurants").localField("restaurant_name").foreignField("name")
                .let(newVariable("orders_drink").forField("drink"))
                .pipeline(match(ctx -> new Document("$expr", new Document("$in", List.of("$$orders_drink", "$beverages")))))
                .as("matches")
 

Returns:

new instance of LookupOperation.LookupOperationBuilder.

Since:

4.1

count

public static CountOperation.CountOperationBuilder count()

Creates a new CountOperation.CountOperationBuilder.

Returns:

never null.

Since:

1.10

redact

public static RedactOperation redact(AggregationExpression condition)

Creates a new RedactOperation that can restrict the content of a document based on information stored within the document itself.

 Aggregation.redact(ConditionalOperators.when(Criteria.where("level").is(5)) //
                .then(RedactOperation.PRUNE) //
                .otherwise(RedactOperation.DESCEND));
 

Parameters:

condition - Any AggregationExpression that resolves to $$DESCEND, $$PRUNE, or $$KEEP. Must not be null.

Returns:

new instance of RedactOperation. Never null.

Since:

3.0

fields

public static Fields fields(String... fields)

Creates a new Fields instance for the given field names.

Parameters:

fields - must not be null.

Returns:

new instance of Fields.

See Also:

• Fields.fields(String...)

bind

public static Fields bind(String name,
 String target)

Creates a new Fields instance from the given field name and target reference.

Parameters:

name - must not be null or empty.

target - must not be null or empty.

Returns:

new instance of Fields.

newAggregationOptions

public static AggregationOptions.Builder newAggregationOptions()

Returns a new AggregationOptions.Builder.

Returns:

new instance of AggregationOptions.Builder.

Since:

1.6

toPipeline

public List<org.bson.Document> toPipeline(AggregationOperationContext rootContext)

Renders this Aggregation specification to an aggregation pipeline returning a List of Document.

Returns:

the aggregation pipeline representing this aggregation.

Since:

2.1

getPipeline

public AggregationPipeline getPipeline()

Returns:

the AggregationPipeline.

Since:

3.0.2

toDocument

public org.bson.Document toDocument(String inputCollectionName,
 AggregationOperationContext rootContext)

Converts this Aggregation specification to a Document.
MongoDB requires as of 3.6 cursor-based aggregation. Use toPipeline(AggregationOperationContext) to render an aggregation pipeline.

Parameters:

inputCollectionName - the name of the input collection.

Returns:

the Document representing this aggregation.

toString

public String toString()

Overrides:

toString in class Object