Aggregation
On this page
Overview
In this guide, you can learn how to use aggregation operations in the MongoDB Node.js driver.
Aggregation operations are expressions you can use to produce reduced and summarized results in MongoDB. MongoDB's aggregation pipeline, part of the Query API, allows you to create a pipeline that consists of one or more stages, each of which performs a specific operation on your data.
You can think of the aggregation pipeline as similar to an automobile factory. Automobile manufacturing requires the use of assembly stations organized into assembly lines. Each station has specialized tools, such as drills and welders. The factory transforms and assembles the initial parts and materials into finished products.
The aggregation pipeline is the assembly line, aggregation stages are the assembly stations, and operator expressions are the specialized tools.
Aggregation vs. Query Operations
Using query operations, such as the find() method, you can perform the following actions:
Select which documents to return.
Select which fields to return.
Sort the results.
Using aggregation operations, you can perform the following actions:
Perform all query operations.
Rename fields.
Calculate fields.
Summarize data.
Group values.
Aggregation operations have some limitations:
Returned documents must not violate the BSON-document size limit of 16 megabytes.
Pipeline stages have a memory limit of 100 megabytes by default. If necessary, you may exceed this limit by setting the
allowDiskUseproperty ofAggregateOptionstotrue. See the AggregateOptions API documentation for more details.
Important
$graphLookup exception
The $graphLookup stage has a strict
memory limit of 100 megabytes and will ignore allowDiskUse.
Useful References
Runnable Examples
The example uses sample data about restaurants. The following code
inserts data into the restaurants collection of the aggregation
database:
const db = client.db("aggregation"); const coll = db.collection("restaurants"); const docs = [ { stars: 3, categories: ["Bakery", "Sandwiches"], name: "Rising Sun Bakery" }, { stars: 4, categories: ["Bakery", "Cafe", "Bar"], name: "Cafe au Late" }, { stars: 5, categories: ["Coffee", "Bakery"], name: "Liz's Coffee Bar" }, { stars: 3, categories: ["Steak", "Seafood"], name: "Oak Steakhouse" }, { stars: 4, categories: ["Bakery", "Dessert"], name: "Petit Cookie" }, ]; const result = await coll.insertMany(docs);
Tip
For more information on connecting to your MongoDB deployment, see the Connection Guide.
Aggregation Example
To perform an aggregation, pass a list of aggregation stages to the
collection.aggregate() method.
In the example, the aggregation pipeline uses the following aggregation stages:
A $match stage to filter for documents whose
categoriesarray field contains the elementBakery.A $group stage to group the matching documents by the
starsfield, accumulating a count of documents for each distinct value ofstars.
const pipeline = [ { $match: { categories: "Bakery" } }, { $group: { _id: "$stars", count: { $sum: 1 } } } ]; const aggCursor = coll.aggregate(pipeline); for await (const doc of aggCursor) { console.log(doc); }
This example should produce the following output:
{ _id: 4, count: 2 } { _id: 3, count: 1 } { _id: 5, count: 1 }
For more information, see the aggregate() API documentation.
Additional Aggregation Examples
You can find another aggregation pipeline example in this MongoDB Blog post.