Aggregation

On this page

Overview
Analogy
Comparing Aggregation and Query Operations
References
Runnable Examples
Aggregation Example
Aggregation Tutorials
Aggregation Template App
Available Tutorials
Additional Examples

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 of AggregateOptions to true. 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 element Bakery.
A $group stage to group the matching documents by the stars field, accumulating a count of documents for each distinct value of stars.

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

Aggregation Tutorials

Aggregation tutorials provide detailed explanations of common aggregation tasks in a step-by-step format. The tutorials are adapted from examples in the Practical MongoDB Aggregations book by Paul Done.

Each tutorial includes the following sections:

Introduction, which describes the purpose and common use cases of the aggregation type. This section also describes the example and desired outcome that the tutorial demonstrates.
Before You Get Started, which describes the necessary databases, collections, and sample data that you must have before building the aggregation pipeline and performing the aggregation.
Tutorial, which describes how to build and run the aggregation pipeline. This section describes each stage of the completed aggregation tutorial, and then explains how to run and interpret the output of the aggregation.

At the end of each aggregation tutorial, you can find a link to a fully runnable Node.js code file that you can run in your environment.

Tip

To learn more about performing aggregations, see the Aggregation guide.

Aggregation Template App

Before you begin following an aggregation tutorial, you must set up a new Node.js app. You can use this app to connect to a MongoDB deployment, insert sample data into MongoDB, and run the aggregation pipeline in each tutorial.

Tip

To learn how to install the driver and connect to MongoDB, see the Download and Install and Create a MongoDB Deployment steps of the Quick Start guide.

Once you install the driver, create a file called agg_tutorial.js. Paste the following code in this file to create an app template for the aggregation tutorials:

const { MongoClient } = require("mongodb");
// Replace the placeholder with your connection string.
const uri = "<connection string>";
const client = new MongoClient(uri);
async function run() {
  try {
    const aggDB = client.db("agg_tutorials_db");
    // Get a reference to relevant collections.
    // ... const someColl =
    // ... const anotherColl =
    // Delete any existing documents in collections.
    // ... await someColl.deleteMany({});
    // Insert sample data into the collection or collections.
    // ... const someData = [ ... ];
    // ... await someColl.insertMany(someData);
    // Create an empty pipeline array.
    const pipeline = [];
    // Add code to create pipeline stages.
    // ... pipeline.push({ ... })
    // Run the aggregation.
    // ... const aggregationResult = ...
    // Print the aggregation results.
    for await (const document of aggregationResult) {
      console.log(document);
    }
  } finally {
    await client.close();
  }
}
run().catch(console.dir);

Important

In the preceding code, read the code comments to find the sections of the code that you must modify for the tutorial you are following.

If you attempt to run the code without making any changes, you will encounter a connection error.

For every tutorial, you must replace the connection string placeholder with your deployment's connection string.

Tip

To learn how to locate your deployment's connection string, see the Create a Connection String step of the Quick Start guide.

For example, if your connection string is "mongodb+srv://mongodb-example:27017", your connection string assignment resembles the following:

const uri = "mongodb+srv://mongodb-example:27017";

To run the completed file after you modify the template for a tutorial, run the following command in your shell:

node agg_tutorial.js

Available Tutorials

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.

Back

Store Large Files

Filtered Subset