Class Aggregation
java.lang.Object
org.springframework.data.mongodb.core.aggregation.Aggregation
- Direct Known Subclasses:
AggregationUpdate
,TypedAggregation
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
Modifier and TypeFieldDescriptionstatic final String
References the start of the field path being processed in the aggregation pipeline stage.static final AggregationOperationContext
static final AggregationOptions
protected final AggregationPipeline
static final String
A variable to conditionally exclude a field.static final String
References the root document, i.e. the top-level document, currently being processed in the aggregation pipeline stage. -
Constructor Summary
ModifierConstructorDescriptionprotected
Aggregation
(List<AggregationOperation> aggregationOperations) Creates a newAggregation
from the givenAggregationOperation
s.protected
Aggregation
(List<AggregationOperation> aggregationOperations, AggregationOptions options) Creates a newAggregation
from the givenAggregationOperation
s.protected
Aggregation
(AggregationOperation... aggregationOperations) Creates a newAggregation
from the givenAggregationOperation
s. -
Method Summary
Modifier and TypeMethodDescriptionObtain anbuilder
instance to create a newAddFieldsOperation
.protected static List<AggregationOperation>
asAggregationList
(AggregationOperation... aggregationOperations) static Fields
Creates a newFields
instance from the given field name and target reference.static BucketOperation
Creates a newBucketOperation
given groupByField.static BucketOperation
bucket
(AggregationExpression groupByExpression) Creates a newBucketOperation
givengroup-by expression
.static BucketAutoOperation
bucketAuto
(String groupByField, int buckets) Creates a newBucketAutoOperation
given groupByField.static BucketAutoOperation
bucketAuto
(AggregationExpression groupByExpression, int buckets) Creates a newBucketAutoOperation
givengroup-by expression
.count()
Creates a newCountOperation.CountOperationBuilder
.static FacetOperation
facet()
Creates a newFacetOperation
.facet
(AggregationOperation... aggregationOperations) Creates a newFacetOperation.FacetOperationBuilder
givenAggregation
.static Fields
Creates a newFields
instance for the given field names.static GeoNearOperation
Get theAggregationOptions
.graphLookup
(String fromCollection) Creates a newGraphLookupOperation.GraphLookupOperationFromBuilder
to construct aGraphLookupOperation
given fromCollection.static GroupOperation
Creates a newGroupOperation
for the given fields.static GroupOperation
Creates a newGroupOperation
for the givenFields
.static LimitOperation
limit
(long maxElements) Creates a newLimitOperation
limiting the result to the given number of elements.lookup()
Entrypoint for creating$lookup
using a fluent builder API.static LookupOperation
Creates a newLookupOperation
.static LookupOperation
Creates a newLookupOperation
for the givenFields
.static MatchOperation
match
(AggregationExpression expression) Creates a newMatchOperation
using the givenAggregationExpression
.static MatchOperation
Creates a newMatchOperation
using the givenCriteria
.static MatchOperation
match
(CriteriaDefinition criteria) Creates a newMatchOperation
using the givenCriteriaDefinition
.merge()
Obtain abuilder
instance to create a newMergeOperation
.static <T> TypedAggregation<T>
newAggregation
(Class<T> type, List<? extends AggregationOperation> operations) Creates a newTypedAggregation
for the given type andAggregationOperation
s.static <T> TypedAggregation<T>
newAggregation
(Class<T> type, AggregationOperation... operations) Creates a newTypedAggregation
for the given type andAggregationOperation
s.static Aggregation
newAggregation
(List<? extends AggregationOperation> operations) Creates a newAggregation
from the givenAggregationOperation
s.static Aggregation
newAggregation
(AggregationOperation... operations) Creates a newAggregation
from the givenAggregationOperation
s.static AggregationOptions.Builder
Returns a newAggregationOptions.Builder
.static AggregationUpdate
newUpdate
(AggregationOperation... operations) Creates a newAggregationUpdate
from the givenAggregationOperation
s.static OutOperation
Creates a newOutOperation
using the given collection name.static String
A pointer to the previousAggregationOperation
.static ProjectionOperation
Creates a newProjectionOperation
including all top level fields of the given givenClass
.static ProjectionOperation
Creates a newProjectionOperation
including the given fields.static ProjectionOperation
Creates a newProjectionOperation
including the givenFields
.static RedactOperation
redact
(AggregationExpression condition) Creates a newRedactOperation
that can restrict the content of a document based on information stored within the document itself.Factory method to create a newReplaceRootOperation.ReplaceRootDocumentOperationBuilder
to configure aReplaceRootOperation
.static ReplaceRootOperation
replaceRoot
(String fieldName) Factory method to create a newReplaceRootOperation
for the field with the given name.static ReplaceRootOperation
replaceRoot
(AggregationExpression aggregationExpression) Factory method to create a newReplaceRootOperation
for the field with the givenAggregationExpression
.static SampleOperation
sample
(long sampleSize) Creates a newSampleOperation
to select the specified number of documents from its input randomly.static SkipOperation
skip
(long elementsToSkip) Creates a newSkipOperation
skipping the given number of elements.static SortOperation
Factory method to create a newSortOperation
for the givenSort
.static SortOperation
sort
(Sort.Direction direction, String... fields) static SortByCountOperation
sortByCount
(String field) Creates a newSortByCountOperation
given groupByField.static SortByCountOperation
sortByCount
(AggregationExpression groupAndSortExpression) Creates a newSortByCountOperation
givengroup and sort expression
.static AggregationOperation
Creates a newAggregationOperation
taking the givenjson value
as is.static AggregationOperation
stage
(org.bson.conversions.Bson aggregationOperation) Creates a newAggregationOperation
taking the givenbson value
as is.org.bson.Document
toDocument
(String inputCollectionName, AggregationOperationContext rootContext) Converts thisAggregation
specification to aDocument
.List<org.bson.Document>
toPipeline
(AggregationOperationContext rootContext) toString()
static UnwindOperation
Factory method to create a newUnwindOperation
for the field with the given name.static UnwindOperation
Factory method to create a newUnwindOperation
for the field with the given name andpreserveNullAndEmptyArrays
.static UnwindOperation
Factory method to create a newUnwindOperation
for the field with the given name including the name of a new field to hold the array index of the element asarrayIndex
.static UnwindOperation
Factory method to create a newUnwindOperation
for the field with the given name, including the name of a new field to hold the array index of the element asarrayIndex
usingpreserveNullAndEmptyArrays
.withOptions
(AggregationOptions options) Returns a copy of thisAggregation
with the givenAggregationOptions
set.
-
Field Details
-
ROOT
References the root document, i.e. the top-level document, currently being processed in the aggregation pipeline stage. -
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
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
-
DEFAULT_OPTIONS
-
pipeline
-
-
Constructor Details
-
Aggregation
Creates a newAggregation
from the givenAggregationOperation
s.- Parameters:
aggregationOperations
- must not be null or empty.
-
Aggregation
Creates a newAggregation
from the givenAggregationOperation
s.- Parameters:
aggregationOperations
- must not be null or empty.
-
Aggregation
Creates a newAggregation
from the givenAggregationOperation
s.- Parameters:
aggregationOperations
- must not be null.options
- must not be null or empty.
-
-
Method Details
-
newAggregation
Creates a newAggregation
from the givenAggregationOperation
s.- Parameters:
operations
- must not be null or empty.
-
newAggregation
Creates a newAggregation
from the givenAggregationOperation
s.- Parameters:
operations
- must not be null or empty.
-
newUpdate
Creates a newAggregationUpdate
from the givenAggregationOperation
s.- Parameters:
operations
- can be empty but must not be null.- Returns:
- new instance of
AggregationUpdate
. - Since:
- 3.0
-
withOptions
Returns a copy of thisAggregation
with the givenAggregationOptions
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 newTypedAggregation
for the given type andAggregationOperation
s.- 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 newTypedAggregation
for the given type andAggregationOperation
s.- 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
Get theAggregationOptions
.- Returns:
- never null.
- Since:
- 2.1
-
previousOperation
A pointer to the previousAggregationOperation
.- Returns:
-
addFields
Obtain anbuilder
instance to create a newAddFieldsOperation
.
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:
-
stage
Creates a newAggregationOperation
taking the givenbson 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
Creates a newAggregationOperation
taking the givenjson 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
Creates a newProjectionOperation
including the given fields.- Parameters:
fields
- must not be null.- Returns:
- new instance of
ProjectionOperation
.
-
project
Creates a newProjectionOperation
including the givenFields
.- Parameters:
fields
- must not be null.- Returns:
- new instance of
ProjectionOperation
.
-
project
Creates a newProjectionOperation
including all top level fields of the given givenClass
.- Parameters:
type
- must not be null.- Returns:
- new instance of
ProjectionOperation
. - Since:
- 2.2
-
unwind
Factory method to create a newUnwindOperation
for the field with the given name.- Parameters:
field
- must not be null or empty.- Returns:
- new instance of
UnwindOperation
.
-
replaceRoot
Factory method to create a newReplaceRootOperation
for the field with the given name.- Parameters:
fieldName
- must not be null or empty.- Returns:
- new instance of
ReplaceRootOperation
. - Since:
- 1.10
-
replaceRoot
Factory method to create a newReplaceRootOperation
for the field with the givenAggregationExpression
.- Parameters:
aggregationExpression
- must not be null.- Returns:
- new instance of
ReplaceRootOperation
. - Since:
- 1.10
-
replaceRoot
Factory method to create a newReplaceRootOperation.ReplaceRootDocumentOperationBuilder
to configure aReplaceRootOperation
.- Returns:
- the ReplaceRootDocumentOperationBuilder.
- Since:
- 1.10
-
unwind
Factory method to create a newUnwindOperation
for the field with the given name andpreserveNullAndEmptyArrays
. 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
Factory method to create a newUnwindOperation
for the field with the given name including the name of a new field to hold the array index of the element asarrayIndex
. 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 newUnwindOperation
for the field with the given name, including the name of a new field to hold the array index of the element asarrayIndex
usingpreserveNullAndEmptyArrays
. 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
Creates a newGroupOperation
for the given fields.- Parameters:
fields
- must not be null.- Returns:
- new instance of
GroupOperation
.
-
group
Creates a newGroupOperation
for the givenFields
.- Parameters:
fields
- must not be null.- Returns:
-
graphLookup
Creates a newGraphLookupOperation.GraphLookupOperationFromBuilder
to construct aGraphLookupOperation
given fromCollection.- Parameters:
fromCollection
- must not be null or empty.- Returns:
- new instance of
GraphLookupOperation.StartWithBuilder
for creating aGraphLookupOperation
. - Since:
- 1.10
-
sort
Factory method to create a newSortOperation
for the givenSort
.- Parameters:
sort
- must not be null.- Returns:
- new instance of
SortOperation
.
-
sort
- Parameters:
direction
- must not be null.fields
- must not be null.- Returns:
- new instance of
SortOperation
.
-
sortByCount
Creates a newSortByCountOperation
given groupByField.- Parameters:
field
- must not be null or empty.- Returns:
- new instance of
SortByCountOperation
. - Since:
- 2.1
-
sortByCount
Creates a newSortByCountOperation
givengroup and sort expression
.- Parameters:
groupAndSortExpression
- must not be null.- Returns:
- new instance of
SortByCountOperation
. - Since:
- 2.1
-
skip
Creates a newSkipOperation
skipping the given number of elements.- Parameters:
elementsToSkip
- must not be less than zero.- Returns:
- new instance of
SkipOperation
.
-
limit
Creates a newLimitOperation
limiting the result to the given number of elements.- Parameters:
maxElements
- must not be less than zero.- Returns:
- new instance of
LimitOperation
.
-
sample
Creates a newSampleOperation
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
Creates a newMatchOperation
using the givenCriteria
.- Parameters:
criteria
- must not be null.- Returns:
- new instance of
MatchOperation
.
-
match
Creates a newMatchOperation
using the givenCriteriaDefinition
.- Parameters:
criteria
- must not be null.- Returns:
- new instance of
MatchOperation
. - Since:
- 1.10
-
match
Creates a newMatchOperation
using the givenAggregationExpression
.- Parameters:
expression
- must not be null.- Returns:
- new instance of
MatchOperation
. - Since:
- 3.3
-
geoNear
Creates a newGeoNearOperation
instance from the givenNearQuery
and thedistanceField
. ThedistanceField
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
Obtain abuilder
instance to create a newMergeOperation
.- Returns:
- new instance of
MergeOperation.MergeOperationBuilder
. - Since:
- 3.0
- See Also:
-
out
Creates a newOutOperation
using the given collection name. This operation must be the last operation in the pipeline.- Parameters:
outCollectionName
- collection name to export aggregation results. TheOutOperation
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
Creates a newBucketOperation
given groupByField.- Parameters:
groupByField
- must not be null or empty.- Returns:
- new instance of
BucketOperation
. - Since:
- 1.10
-
bucket
Creates a newBucketOperation
givengroup-by expression
.- Parameters:
groupByExpression
- must not be null.- Returns:
- new instance of
BucketOperation
. - Since:
- 1.10
-
bucketAuto
Creates a newBucketAutoOperation
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
Creates a newBucketAutoOperation
givengroup-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
Creates a newFacetOperation
.- Returns:
- new instance of
FacetOperation
. - Since:
- 1.10
-
facet
public static FacetOperation.FacetOperationBuilder facet(AggregationOperation... aggregationOperations) Creates a newFacetOperation.FacetOperationBuilder
givenAggregation
.- 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 newLookupOperation
.- 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
Creates a newLookupOperation
for the givenFields
.- 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
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
Creates a newCountOperation.CountOperationBuilder
.- Returns:
- never null.
- Since:
- 1.10
-
redact
Creates a newRedactOperation
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
- AnyAggregationExpression
that resolves to $$DESCEND, $$PRUNE, or $$KEEP. Must not be null.- Returns:
- new instance of
RedactOperation
. Never null. - Since:
- 3.0
-
fields
Creates a newFields
instance for the given field names.- Parameters:
fields
- must not be null.- Returns:
- new instance of
Fields
. - See Also:
-
bind
Creates a newFields
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
Returns a newAggregationOptions.Builder
.- Returns:
- new instance of
AggregationOptions.Builder
. - Since:
- 1.6
-
toPipeline
- Returns:
- the aggregation pipeline representing this aggregation.
- Since:
- 2.1
-
getPipeline
- Returns:
- the
AggregationPipeline
. - Since:
- 3.0.2
-
toDocument
public org.bson.Document toDocument(String inputCollectionName, AggregationOperationContext rootContext) Converts thisAggregation
specification to aDocument
.
MongoDB requires as of 3.6 cursor-based aggregation. UsetoPipeline(AggregationOperationContext)
to render an aggregation pipeline.- Parameters:
inputCollectionName
- the name of the input collection.- Returns:
- the
Document
representing this aggregation.
-
toString
-