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 framework allows you to create a pipeline that consists of one or more stages, each of which performs a specific operation on your data.
Analogy
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 expression operators are the specialized tools.
Comparing Aggregation and 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. You can exceed this limit by setting the
allowDiskUse
property ofAggregateOptions
totrue
. 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
.
References
To view a full list of expression operators, see Aggregation Operators in the Server manual.
To learn about assembling an aggregation pipeline and view examples, see Aggregation Pipeline in the Server manual.
To learn more about creating pipeline stages, see Aggregation Stages in the Server manual.
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"); // Create sample documents 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" }, ]; // Insert documents into the restaurants collection 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
categories
array field contains the elementBakery
.A $group stage to group the matching documents by the
stars
field, accumulating a count of documents for each distinct value ofstars
.
// Define an aggregation pipeline with a match stage and a group stage const pipeline = [ { $match: { categories: "Bakery" } }, { $group: { _id: "$stars", count: { $sum: 1 } } } ]; // Execute the aggregation const aggCursor = coll.aggregate(pipeline); // Print the aggregated results for await (const doc of aggCursor) { console.log(doc); }
This example produces the following output:
{ _id: 4, count: 2 } { _id: 3, count: 1 } { _id: 5, count: 1 }
For more information, see the aggregate() API documentation.
Additional Examples
To view step-by-step explanations of common aggregation tasks, see the Aggregation Tutorials.
You can find another aggregation pipeline example in the Aggregation Framework with Node.js Tutorial blog post on the MongoDB website.