Aggregates Builders
On this page
- Overview
- Match
- Project
- Projecting Computed Fields
- Documents
- Sample
- Sort
- Skip
- Limit
- Lookup
- Left Outer Join
- Full Join and Uncorrelated Subqueries
- Group
- Pick-N Accumulators
- MinN
- MaxN
- FirstN
- LastN
- Top
- TopN
- Bottom
- BottomN
- Unwind
- Out
- Merge
- GraphLookup
- SortByCount
- ReplaceRoot
- AddFields
- Count
- Bucket
- BucketAuto
- Facet
- SetWindowFields
- Densify
- Fill
- Atlas Full-Text Search
- Atlas Search Metadata
Overview
In this guide, you can learn how to use the Aggregates class which provides static factory methods that build aggregation pipeline stages in the MongoDB Java driver.
To learn more about aggregation, see our Aggregation guide. To learn how to create expression operations with discoverable, typesafe Java methods to use in your aggregations, see Aggregation Expression Operations.
Tip
For brevity, you may choose to import the methods of the following classes statically to make your queries more succinct:
Aggregates
Filters
Projections
Sorts
Accumulators
import static com.mongodb.client.model.Aggregates.*; import static com.mongodb.client.model.Filters.*; import static com.mongodb.client.model.Projections.*; import static com.mongodb.client.model.Sorts.*; import static com.mongodb.client.model.Accumulators.*; import static java.util.Arrays.asList;
The examples on this page assume these static imports, in addition to
statically importing the asList()
method.
Use these methods to construct pipeline stages and specify them in your aggregation as a list:
Bson matchStage = match(eq("some_field", "some_criteria")); Bson sortByCountStage = sortByCount("some_field"); collection.aggregate(asList(matchStage, sortByCountStage)).forEach(doc -> System.out.println(doc));
Match
Use the match()
method to create a $match
pipeline stage that matches incoming documents against the specified
query filter, filtering out documents that do not match.
Tip
The filter can be an instance of any class that implements Bson
, but it's
convenient to combine with use of the Filters class.
The following example creates a pipeline stage that matches all documents where the
title
field is equal to "The Shawshank Redemption":
match(eq("title", "The Shawshank Redemption"));
Project
Use the project()
method to create a $project
pipeline stage that project specified document fields. Field projection
in aggregation follows the same rules as field projection in queries.
Tip
Though the projection can be an instance of any class that implements Bson
,
it's convenient to combine with use of Projections.
The following example creates a pipeline stage that excludes the _id
field but
includes the title
and plot
fields:
project(fields(include("title", "plot"), excludeId()));
Projecting Computed Fields
The $project
stage can project computed fields as well.
The following example creates a pipeline stage that projects the rated
field
into a new field called rating
, effectively renaming the field.
project(fields(computed("rating", "$rated"), excludeId()));
Documents
Use the documents()
method to create a
$documents
pipeline stage that returns literal documents from input values.
Important
If you use a $documents
stage in an aggregation pipeline, it must be the first
stage in the pipeline.
The following example creates a pipeline stage that creates
sample documents with a title
field:
documents(asList( new Document("title", "The Shawshank Redemption"), new Document("title", "Back to the Future"), new Document("title", "Jurassic Park")));
Important
If you use the documents()
method to provide the input to an aggregation pipeline,
you must call the aggregate()
method on a database instead of on a
collection.
Sample
Use the sample()
method to create a $sample
pipeline stage to randomly select documents from input.
The following example creates a pipeline stage that randomly selects 5 documents:
sample(5);
Sort
Use the sort()
method to create a $sort
pipeline stage to sort by the specified criteria.
Tip
Though the sort criteria can be an instance of any class that
implements Bson
, it's convenient to combine with use of Sorts.
The following example creates a pipeline stage that sorts in descending order according
to the value of the year
field and then in ascending order according to the
value of the title
field:
sort(orderBy(descending("year"), ascending("title")));
Skip
Use the skip()
method to create a $skip
pipeline stage to skip over the specified number of documents before
passing documents into the next stage.
The following example creates a pipeline stage that skips the first 5
documents:
skip(5);
Limit
Use the $limit pipeline stage to limit the number of documents passed to the next stage.
The following example creates a pipeline stage that limits the number of documents to 10
:
limit(10);
Lookup
Use the lookup()
method to create a $lookup
pipeline stage to perform joins and uncorrelated subqueries between two collections.
Left Outer Join
The following example creates a pipeline stage that performs a left outer
join between the movies
and comments
collections:
It joins the
_id
field frommovies
to themovie_id
field incomments
It outputs the results in the
joined_comments
field:
lookup("comments", "_id", "movie_id", "joined_comments");
Full Join and Uncorrelated Subqueries
The following example creates a pipeline stage that joins two collections, orders
and warehouses
, by the item and whether the available quantity is enough
to fulfill the ordered quantity:
List<Variable<String>> variables = asList(new Variable<>("order_item", "$item"), new Variable<>("order_qty", "$ordered")); List<Bson> pipeline = asList( match(expr(new Document("$and", asList(new Document("$eq", asList("$$order_item", "$stock_item")), new Document("$gte", asList("$instock", "$$order_qty")))))), project(fields(exclude("stock_item"), excludeId()))); List<Bson> innerJoinLookup = lookup("warehouses", variables, pipeline, "stockdata");
Group
Use the group()
method to create a $group
pipeline stage to group documents by a specified expression and output a document
for each distinct grouping.
Tip
The driver includes the Accumulators class with static factory methods for each of the supported accumulators.
The following example creates a pipeline stage that groups documents by the value
of the customerId
field. Each group accumulates the sum and average
of the values of the quantity
field into the totalQuantity
and
averageQuantity
fields.
group("$customerId", sum("totalQuantity", "$quantity"), avg("averageQuantity", "$quantity"));
Learn more about accumulator operators from the Server manual section on Accumulators.
Pick-N Accumulators
The pick-n accumulators are aggregation accumulation operators that return the top and bottom elements given a specific ordering. Use one of the following builders to create an aggregation accumulation operator:
Tip
You can only perform aggregation operations with these pick-n accumulators when running MongoDB v5.2 or later.
Learn which aggregation pipeline stages you can use accumulator operators with from the Server manual section on Accumulators.
MinN
The minN()
builder creates the $minN
accumulator which returns data from documents that contain the n
lowest
values of a grouping.
Tip
The $minN
and $bottomN
accumulators can perform similar tasks.
See
Comparison of $minN and $bottomN Accumulators
for recommended usage of each.
The following example demonstrates how to use the minN()
method to return
the lowest three imdb.rating
values for movies, grouped by year
:
group( "$year", minN( "lowest_three_ratings", new BsonString("$imdb.rating"), 3 ));
See the minN() API documentation for more information.
MaxN
The maxN()
accumulator returns data from documents that contain the n
highest values of a grouping.
The following example demonstrates how to use the maxN()
method to
return the highest two imdb.rating
values for movies, grouped by year
:
group( "$year", maxN( "highest_two_ratings", new BsonString("$imdb.rating"), 2 ));
See the maxN() API documentation for more information.
FirstN
The firstN()
accumulator returns data from the first n
documents in
each grouping for the specified sort order.
Tip
The $firstN
and $topN
accumulators can perform similar tasks.
See
Comparison of $firstN and $topN Accumulators
for recommended usage of each.
The following example demonstrates how to use the firstN()
method to
return the first four movie title
values, based on the order they came
into the stage, grouped by year
:
group( "$year", firstN( "first_four_movies", new BsonString("$title"), 4 ));
See the firstN() API documentation for more information.
LastN
The lastN()
accumulator returns data from the last n
documents in
each grouping for the specified sort order.
The following example demonstrates how to use the lastN()
method to show
the last three movie title
values, based on the the order they came into
the stage, grouped by year
:
group( "$year", lastN( "last_three_movies", new BsonString("$title"), 3 ));
See the lastN() API documentation for more information.
Top
The top()
accumulator returns data from the first document in a group
based on the specified sort order.
The following example demonstrates how to use the top()
method to return
the title
and imdb.rating
values for the top rated movies based on the
imdb.rating
, grouped by year
.
group( "$year", top( "top_rated_movie", descending("imdb.rating"), asList(new BsonString("$title"), new BsonString("$imdb.rating")) ));
See the top() API documentation for more information.
TopN
The topN()
accumulator returns data from documents that contain the
highest n
values for the specified field.
Tip
The $firstN
and $topN
accumulators can perform similar tasks.
See
Comparison of $firstN and $topN Accumulators
for recommended usage of each.
The following example demonstrates how to use the topN()
method to return
the title
and runtime
values of the three longest movies based on the
runtime
values, grouped by year
.
group( "$year", topN( "longest_three_movies", descending("runtime"), asList(new BsonString("$title"), new BsonString("$runtime")), 3 ));
See the topN() API documentation for more information.
Bottom
The bottom()
accumulator returns data from the last document in a group
based on the specified sort order.
The following example demonstrates how to use the bottom()
method to
return the title
and runtime
values of the shortest movie based on the
runtime
value, grouped by year
.
group( "$year", bottom( "shortest_movies", descending("runtime"), asList(new BsonString("$title"), new BsonString("$runtime")) ));
See the bottom() API documentation for more information.
BottomN
The bottomN()
accumulator returns data from documents that contain the
lowest n
values for the specified field.
Tip
The $minN
and $bottomN
accumulators can perform similar tasks.
See Comparison of $minN and $bottomN Accumulators
for recommended usage of each.
The following example demonstrates how to use the bottomN()
method to
return the title
and imdb.rating
values of the two lowest rated movies
based on the imdb.rating
value, grouped by year
:
group( "$year", bottomN( "lowest_rated_two_movies", descending("imdb.rating"), asList(new BsonString("$title"), new BsonString("$imdb.rating")), 2 ));
See the bottomN() API documentation for more information.
Unwind
Use the unwind()
method to create an $unwind
pipeline stage to deconstruct an array field from input documents, creating
an output document for each array element.
The following example creates a document for each element in the sizes
array:
unwind("$sizes");
To preserve documents that have missing or null
values for the array field, or where array is empty:
unwind("$sizes", new UnwindOptions().preserveNullAndEmptyArrays(true));
To include the array index, in this example in a field called "position"
:
unwind("$sizes", new UnwindOptions().includeArrayIndex("position"));
Out
Use the out()
method to create an $out
pipeline stage that writes all documents to the specified collection in
the same database.
Important
The $out
stage must be the last stage in any aggregation pipeline.
The following example writes the results of the pipeline to the authors
collection:
out("authors");
Merge
Use the merge()
method to create a $merge
pipeline stage that merges all documents into the specified collection.
Important
The $merge
stage must be the last stage in any aggregation pipeline.
The following example merges the pipeline into the authors
collection using the default
options:
merge("authors");
The following example merges the pipeline into the customers
collection in the
reporting
database using some options that specify to replace
the document if both date
and customerId
match, otherwise insert the
document:
merge(new MongoNamespace("reporting", "customers"), new MergeOptions().uniqueIdentifier(asList("date", "customerId")) .whenMatched(MergeOptions.WhenMatched.REPLACE) .whenNotMatched(MergeOptions.WhenNotMatched.INSERT));
GraphLookup
Use the graphLookup()
method to create a $graphLookup
pipeline stage that performs a recursive search on a specified collection to match
a specified field in one document to a specified field of another document.
The following example computes the social network graph for users in the
contacts
collection, recursively matching the value in the friends
field
to the name
field:
graphLookup("contacts", "$friends", "friends", "name", "socialNetwork");
Using GraphLookupOptions
, you can specify the depth to recurse as well as
the name of the depth field, if desired. In this example, $graphLookup
will
recurse up to two times, and create a field called degrees
with the
recursion depth information for every document.
graphLookup("contacts", "$friends", "friends", "name", "socialNetwork", new GraphLookupOptions().maxDepth(2).depthField("degrees"));
Using GraphLookupOptions
, you can specify a filter that documents must match
in order for MongoDB to include them in your search. In this
example, only links with "golf" in their hobbies
field will be included.
graphLookup("contacts", "$friends", "friends", "name", "socialNetwork", new GraphLookupOptions().maxDepth(1).restrictSearchWithMatch(eq("hobbies", "golf")));
SortByCount
Use the sortByCount()
method to create a $sortByCount
pipeline stage that groups documents by a given expression and then sorts
these groups by count in descending order.
Tip
The $sortByCount
stage is identical to a $group
stage with a
$sum
accumulator followed by a $sort
stage.
[ { "$group": { "_id": <expression to group on>, "count": { "$sum": 1 } } }, { "$sort": { "count": -1 } } ]
The following example groups documents by the truncated value of the field x
and computes the count for each distinct value:
sortByCount(new Document("$floor", "$x"));
ReplaceRoot
Use the replaceRoot()
method to create a $replaceRoot
pipeline stage that replaces each input document with the specified document.
The following example replaces each input document with the nested document
in the spanish_translation
field:
replaceRoot("$spanish_translation");
AddFields
Use the addFields()
method to create an $addFields
pipeline stage that adds new fields to documents.
Tip
Use $addFields
when you do not want to project field inclusion
or exclusion.
The following example adds two new fields, a
and b
to the input documents:
addFields(new Field("a", 1), new Field("b", 2));
Count
Use the count()
method to create a $count
pipeline stage that counts the number of documents that enter the stage, and assigns
that value to a specified field name. If you do not specify a field,
count()
defaults the field name to "count".
Tip
The $count
stage is syntactic sugar for:
{ "$group":{ "_id": 0, "count": { "$sum" : 1 } } }
The following example creates a pipeline stage that outputs the count of incoming documents in a field called "total":
count("total");
Bucket
Use the bucket()
method to create a $bucket
pipeline stage that automates the bucketing of data around predefined boundary
values.
The following example creates a pipeline stage that groups incoming documents based
on the value of their screenSize
field, inclusive of the lower boundary
and exclusive of the upper boundary.
bucket("$screenSize", asList(0, 24, 32, 50, 70, 200));
Use the BucketOptions
class to specify a default bucket for values
outside of the specified boundaries, and to specify additional accumulators.
The following example creates a pipeline stage that groups incoming documents based
on the value of their screenSize
field, counting the number of documents
that fall within each bucket, pushing the value of screenSize
into a
field called matches
, and capturing any screen sizes greater than "70"
into a bucket called "monster" for monstrously large screen sizes:
Tip
The driver includes the Accumulators class with static factory methods for each of the supported accumulators.
bucket("$screenSize", asList(0, 24, 32, 50, 70), new BucketOptions().defaultBucket("monster").output(sum("count", 1), push("matches", "$screenSize")));
BucketAuto
Use the bucketAuto()
method to create a $bucketAuto
pipeline stage that automatically determines the boundaries of each bucket
in its attempt to distribute the documents evenly into a specified number of buckets.
The following example creates a pipeline stage that will attempt to create and evenly
distribute documents into 10 buckets using the value of their price
field:
bucketAuto("$price", 10);
Use the BucketAutoOptions
class to specify a preferred number
based scheme to set boundary values, and specify additional accumulators.
The following example creates a pipeline stage that will attempt to create and evenly
distribute documents into 10 buckets using the value of their price
field,
setting the bucket boundaries at powers of 2 (2, 4, 8, 16, ...). It also counts
the number of documents in each bucket, and calculates their average price
in a new field called avgPrice
:
Tip
The driver includes the Accumulators class with static factory methods for each of the supported accumulators.
bucketAuto("$price", 10, new BucketAutoOptions().granularity(BucketGranularity.POWERSOF2) .output(sum("count", 1), avg("avgPrice", "$price")));
Facet
Use the facet()
method to create a $facet
pipeline stage that allows for the definition of parallel pipelines.
The following example creates a pipeline stage that executes two parallel aggregations:
The first aggregation distributes incoming documents into 5 groups according to their
attributes.screen_size
field.The second aggregation counts all manufacturers and returns their count, limited to the top 5.
facet(new Facet("Screen Sizes", bucketAuto("$attributes.screen_size", 5, new BucketAutoOptions().output(sum("count", 1)))), new Facet("Manufacturer", sortByCount("$attributes.manufacturer"), limit(5)));
SetWindowFields
Use the setWindowFields()
method to create a $setWindowFields
pipeline stage that allows using window operators to perform operations
on a specified span of documents in a collection.
Tip
Window Functions
The driver includes the Windows class with static factory methods for building windowed computations.
The following example creates a pipeline stage that computes the
accumulated rainfall and the average temperature over the past month for
each locality from more fine-grained measurements presented in the rainfall
and temperature
fields:
Window pastMonth = Windows.timeRange(-1, MongoTimeUnit.MONTH, Windows.Bound.CURRENT); setWindowFields("$localityId", Sorts.ascending("measurementDateTime"), WindowOutputFields.sum("monthlyRainfall", "$rainfall", pastMonth), WindowOutputFields.avg("monthlyAvgTemp", "$temperature", pastMonth));
Densify
Use the densify()
method to create a
$densify
pipeline stage that generates a sequence of documents to span a specified
interval.
Tip
You can use the $densify()
aggregation stage only when running
MongoDB v5.1 or later.
Consider the following documents retrieved from the Atlas sample weather dataset
that contain measurements for a similar position
field, spaced one hour
apart:
Document{{ _id=5553a..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:00:00 EST 1984, ... }} Document{{ _id=5553b..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 09:00:00 EST 1984, ... }}
Suppose you needed to create a pipeline stage that performs the following actions on these documents:
Add a document at every 15-minute interval for which a
ts
value does not already exist.Group the documents by the
position
field.
The call to the densify()
aggregation stage builder that accomplishes
these actions should resemble the following:
densify( "ts", DensifyRange.partitionRangeWithStep(15, MongoTimeUnit.MINUTE), DensifyOptions.densifyOptions().partitionByFields("position.coordinates"));
The following output highlights the documents generated by the aggregate stage
which contain ts
values every 15 minutes between the existing documents:
Document{{ _id=5553a..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:00:00 EST 1984, ... }} Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:15:00 EST 1984 }} Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:30:00 EST 1984 }} Document{{ position=Document{{coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 08:45:00 EST 1984 }} Document{{ _id=5553b..., position=Document{{type=Point, coordinates=[-47.9, 47.6]}}, ts=Mon Mar 05 09:00:00 EST 1984, ... }}
See the densify package API documentation for more information.
Fill
Use the fill()
method to create a
$fill
pipeline stage that populates null
and missing field values.
Tip
You can use the $fill()
aggregation stage only when running
MongoDB v5.3 or later.
Consider the following documents that contain temperature and air pressure measurements at an hourly interval:
Document{{_id=6308a..., hour=1, temperature=23C, air_pressure=29.74}} Document{{_id=6308b..., hour=2, temperature=23.5C}} Document{{_id=6308c..., hour=3, temperature=null, air_pressure=29.76}}
Suppose you needed to populate missing temperature and air pressure data points in the documents as follows:
Populate the
air_pressure
field for hour "2" using linear interpolation to calculate the value.Set the missing
temperature
value to "23.6C" for hour "3".
The call to the fill()
aggregation stage builder that accomplishes
these actions resembles the following:
fill( FillOptions.fillOptions().sortBy(ascending("hour")), FillOutputField.value("temperature", "23.6C"), FillOutputField.linear("air_pressure") );
The following output highlights the documents that contain fields populated by the aggregate stage:
Document{{_id=6308a..., hour=1, temperature=23C, air_pressure=29.74}} Document{{_id=6308b..., hour=2, temperature=23.5C, air_pressure=29.75}} Document{{_id=6308c..., hour=3, temperature=23.6C, air_pressure=29.76}}
See the fill package API documentation for more information.
Atlas Full-Text Search
Use the search()
method to create a $search
pipeline stage that specifies a full-text search of one or more fields.
Tip
Only Available on Atlas for MongoDB v4.2 and later
This aggregation pipeline operator is only available for collections hosted on MongoDB Atlas clusters running v4.2 or later that are covered by an Atlas search index. Learn more about the required setup and the functionality of this operator from the Atlas Search documentation.
The following example creates a pipeline stage that searches the title
field for text that contains the word "Future":
Bson textSearch = Aggregates.search( SearchOperator.text( SearchPath.fieldPath("title"), "Future"));
Learn more about the builders from the search package API documentation.
Atlas Search Metadata
Use the searchMeta()
method to create a
$searchMeta
pipeline stage which returns only the metadata part of the results from
Atlas full-text search queries.
Tip
Only Available on Atlas for MongoDB v4.4.11 and later
This aggregation pipeline operator is only available on MongoDB Atlas clusters running v4.4.11 and later. For a detailed list of version availability, see the MongoDB Atlas documentation on $searchMeta.
The following example shows the count
metadata for an Atlas search
aggregation stage:
Aggregates.searchMeta( SearchOperator.near(2010, 1, SearchPath.fieldPath("year")));
Learn more about this helper from the searchMeta() API documentation.