Aggregates Builders

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.

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 com.mongodb.client.model.search.SearchPath.fieldPath;
import static com.mongodb.client.model.search.VectorSearchOptions.exactVectorSearchOptions;
import static java.util.Arrays.asList;

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.

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.

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()));

project(fields(computed("rating", "$rated"), excludeId()));

Documents

Use the documents() method to create a $documents pipeline stage that returns literal documents from input values.

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")));

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.

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.

lookup("comments", "_id", "movie_id", "joined_comments");

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())));
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.

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:

• minN()

• maxN()

• firstN()

• lastN()

• top()

• topN()

• bottom()

• bottomN()

Learn which aggregation pipeline stages you can use accumulator operators with from the Server manual section on Accumulators.

group(
        "$year",
        minN(
                "lowest_three_ratings",
                new BsonString("$imdb.rating"),
                3
                ));

group(
        "$year",
        maxN(
                "highest_two_ratings",
                new BsonString("$imdb.rating"),
                2
                ));

group(
        "$year",
        firstN(
                "first_four_movies",
                new BsonString("$title"),
                4
                ));

group(
        "$year",
        lastN(
                "last_three_movies",
                new BsonString("$title"),
                3
                ));

group(
        "$year", 
        top(
                "top_rated_movie",
                descending("imdb.rating"),
                asList(new BsonString("$title"), new BsonString("$imdb.rating"))
                ));

group(
        "$year", 
        topN(
                "longest_three_movies",
                descending("runtime"),
                asList(new BsonString("$title"), new BsonString("$runtime")),
                3
                ));

group(
        "$year", 
        bottom(
                "shortest_movies",
                descending("runtime"),
                asList(new BsonString("$title"), new BsonString("$runtime"))
                ));

group(
        "$year", 
        bottomN(
                "lowest_rated_two_movies",
                descending("imdb.rating"),
                asList(new BsonString("$title"), new BsonString("$imdb.rating")),
                2
                ));

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.

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.

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.

[
    { "$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.

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

{ "$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:

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:

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.

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.

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

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.

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.

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.

Atlas Vector Search

Use the vectorSearch() method to create a $vectorSearch pipeline stage that specifies a semantic search. A semantic search is a type of search which locates information that is similar in meaning.

To use this feature, you must set up a vector search index and index your vector embeddings. To learn about how to programmatically create a vector search index, see the Atlas Search and Vector Search Indexes section in the Indexes guide. To learn more about vector embeddings, see How to Index Vector Embeddings for Vector Search.

The following example shows how to build an aggregation pipeline that uses the vectorSearch() and project() methods to compute a vector search score:

List<Double> queryVector = (asList(-0.0072121937, -0.030757688, -0.012945653));
String indexName = "mflix_movies_embedding_index";
FieldSearchPath fieldSearchPath = fieldPath("plot_embedding");
int limit = 1;
VectorSearchOptions options = exactVectorSearchOptions().filter(gte("year", 2016));
List<Bson> pipeline = asList(
        vectorSearch(
                fieldSearchPath,
                queryVector,
                indexName,
                limit,
                options),
        project(
                metaVectorSearchScore("vectorSearchScore")));

The following example shows how you can print the score from the result of the preceding aggregation pipeline:

Document found = collection.aggregate(pipeline).first();
double score = found.getDouble("vectorSearchScore").doubleValue();
System.out.println("vectorSearch score: " + score);

Learn more about this helper in the vectorSearch() API documentation.