Aggregates class provides static factory methods
that build aggregation pipeline stages.
Each method returns an instance of the
Bson type, which can in turn be passed to the
aggregate method of
For brevity, you may choose to import the methods of the
Aggregates class statically:
All the examples below assume this static import.
$match pipeline stage passes all documents matching the
specified filter to the next stage. Though the filter can be an instance of any class that implements
Bson, it’s convenient to
combine with use of the
Filters class. In the example below, it’s assumed that the
equal method of the
Filters class has been statically imported.
This example creates a pipeline stage that matches all documents where the
author field is equal to
match is a reserved word in scala and has to be escaped by ` (backticks), the
filter alias may be preferred:
$project pipeline stage passes the projected fields of all
documents to the next stage. Though the projection can be an instance of any class that implements
Bson, it’s convenient to combine
with use of the
Projections class. In the example below, it’s assumed that the
fields methods of the
Projections class have been statically imported.
This example creates a pipeline stage that excludes the
_id field but includes the
project(fields(include("title", "author"), excludeId()))
Projecting Computed Fields
$project stage can project computed fields as well.
This example simply projects the
qty field into a new field called
quantity. In other words, it renames the field:
$sample pipeline stage randomly select N documents from its input.
This example creates a pipeline stage that randomly selects 5 documents from the collection:
$sort pipeline stage passes all documents to the next stage,
sorted by the specified sort criteria. Though the sort criteria can be an instance of any class that implements
Bson, it’s convenient to
combine with use of the
Sorts class. In the example below, it’s assumed that the
orderBy methods of the
Sorts class have been statically imported.
This example creates a pipeline stage that sorts in descending order according to the value of the
age field and then in ascending order
according to the value of the
$skip pipeline stage skips over the specified number of
documents that pass into the stage and passes the remaining documents to the next stage.
This example skips the first
$limit pipeline stage limits the number of documents passed
to the next stage.
This example limits the number of documents to
Starting in 3.2, MongoDB provides a new
$lookup pipeline stage
that performs a left outer join with another collection to filter in documents from the joined collection for processing.
This example performs a left outer join on the
fromCollection collection, joining the
local field to the
from field and outputted in
lookup("fromCollection", "local", "from", "joinedOutput")
$group pipeline stage groups documents by some specified
expression and outputs to the next stage a document for each distinct grouping. A group consists of an
_id which specifies the
expression on which to group, and zero or more
accumulators which are evaluated for each
grouping. To simplify the expression of accumulators, the driver includes an
Accumulators singleton object with factory methods
for each of the supported accumulators.
In the example below, it’s assumed that the
avg methods of the
Accumulators class have been statically imported.
This example groups documents by the value of the
customerId field, and for each group accumulates the sum and average of the values of
quantity field into the
averageQuantity fields, respectively.
group("$customerId", sum("totalQuantity", "$quantity"), avg("averageQuantity", "$quantity"))
$unwind pipeline stage deconstructs an array field from the
input documents to output a document for each element.
This example outputs, for each document, a document for each element in the
Available with MongoDB 3.2, this example also includes any documents that have missing or
null values for the
$sizes field or where
$sizes list is empty:
Available with MongoDB 3.2, this example unwinds the
sizes array and also outputs the array index into the
$out pipeline stage outputs all documents to the specified
collection. It must be the last stage in any aggregate pipeline:
This example writes the pipeline to the
$setWindowFields is in beta. Backwards-breaking changes may be made before the final release.
$setWindowFields pipeline stage
allows using window operators. This stage partitions the input documents similarly to the
$group pipeline stage,
optionally sorts them, computes fields in the documents by computing window functions over windows specified per function
(a window is a subset of a partition), and outputs the documents. The important difference from the
$group pipeline stage is that
documents belonging to the same partition or window are not folded into a single document.
The driver includes the
singleton object with factory methods for supported window operators.
This example computes the accumulated rainfall and the average temperature over the past month per each locality
from more fine-grained measurements presented via the
val pastMonth: Window = Windows.timeRange(-1, MongoTimeUnit.MONTH, Windows.Bound.CURRENT) setWindowFields(Some("$localityId"), Some(Sorts.ascending("measurementDateTime")), WindowedComputations.sum("monthlyRainfall", "$rainfall", Some(pastMonth)), WindowedComputations.avg("monthlyAvgTemp", "$temperature", Some(pastMonth)))
Creating a Pipeline
The above pipeline operators are typically combined into a list and passed to the
aggregate method of a
MongoCollection. For instance:
collection.aggregate(List(filter(equal("author", "Dave")), group("$customerId", sum("totalQuantity", "$quantity"), avg("averageQuantity", "$quantity")), out("authors")))