Docs Menu
Docs Home
/
Languages
/
Javascript
/
Node.js
/
Fundamentals

Aggregation

On this page

  • Overview
  • Analogy
  • Aggregation vs. Query Operations
  • Useful References
  • Runnable Examples
  • Aggregation Example
  • 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 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 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.

Useful References

To learn more about aggregation concepts, see the following pages 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");
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 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.

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

Promises