DOCSP-50497 Standardizing Node.js Aggregation Page

mballard-mdb · mballard-mdb · commit 59a2a498bbe5 · 2025-06-09T16:09:08.000-04:00
diff --git a/source/aggregation.txt b/source/aggregation.txt
@@ -31,228 +31,150 @@ Aggregation
 Overview
 --------
 
-In this guide, you can learn how to use **aggregation operations** in
-the MongoDB Node.js driver.
+In this guide, you can learn how to use the MongoDB {+driver+} to perform
+**aggregation operations**.
 
-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.
+Aggregation operations process data in your MongoDB collections and return
+reduced and summarized results. The MongoDB Aggregation framework is modeled on the 
+concept of data processing pipelines. Documents enter a pipeline comprised of one or
+more stages, and this pipeline transforms the documents into an aggregated result.
 
 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 :manual:`limitations </core/aggregation-pipeline-limits/>`:
-
-- Returned documents must not violate the :manual:`BSON-document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
+The aggregation pipeline is similar to an automobile factory assembly line. An
+assembly lines has stations with specialized tools that are used to perform
+specific tasks. For example, when building a car, the assembly line begins with
+a frame. As the car frame moves though the assembly line, each station adds a
+new part. The factory transforms and assembles the initial parts, resulting in
+finished cars.
+
+The *aggregation pipeline* is the assembly line, the *aggregation stages* are
+the assembly stations, and the *expression operators* are the specialized tools.
+
+Compare Aggregation and Find Operations
+---------------------------------------
+
+The following table lists the different tasks you can perform with find
+operations compared to what you can achieve with aggregation
+operations. The aggregation framework provides expanded functionality
+that allows you to transform and manipulate your data.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Find Operations
+     - Aggregation Operations
+
+   * - | Select *certain* documents to return
+       | Select *which* fields to return
+       | Sort the results
+       | Limit the results
+       | Count the results
+     - | Select *certain* documents to return
+       | Select *which* fields to return
+       | Sort the results
+       | Limit the results
+       | Count the results
+       | Group the results
+       | Rename fields
+       | Compute new fields
+       | Summarize data
+       | Connect and merge data sets
+
+Server Limitations
+------------------
+
+Consider the following :manual:`limitations </core/aggregation-pipeline-limits/>` when performing aggregation operations:
+
+- Returned documents must not violate the :manual:`BSON document size limit </reference/limits/#mongodb-limit-BSON-Document-Size>`
   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 <{+api+}/interfaces/AggregateOptions.html>`__
-  for more details.
-
-.. important:: $graphLookup exception
-
-   The :manual:`$graphLookup
-   </reference/operator/aggregation/graphLookup/>` stage has a strict
-   memory limit of 100 megabytes and will ignore ``allowDiskUse``.
+- Pipeline stages have a memory limit of 100 megabytes by default. If required,
+  you can exceed this limit by enabling the `AllowDiskUse
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AggregateOptions.AllowDiskUse.html#MongoDB_Driver_AggregateOptions_AllowDiskUse>`__
+  property of the ``AggregateOptions`` object that you pass to the
+  ``Aggregate()`` method. 
 
-References
-~~~~~~~~~~
+- The :manual:`$graphLookup
+   </reference/operator/aggregation/graphLookup/>` stage has a strict memory
+   limit of 100 megabytes and will ignore the ``AllowDiskUse`` property.
 
-To view a full list of expression operators, see :manual:`Aggregation
-Operators </reference/operator/aggregation/>` in the Server manual.
-
-To learn about assembling an aggregation pipeline and view examples, see
-:manual:`Aggregation Pipeline </core/aggregation-pipeline/>` in the
-Server manual.
-
-To learn more about creating pipeline stages, see :manual:`Aggregation
-Stages </reference/operator/aggregation-pipeline/>` 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:
-
-.. literalinclude:: /code-snippets/aggregation/agg.js
-   :start-after: begin data insertion
-   :end-before: end data insertion
-   :language: javascript
-   :dedent:
-
-.. tip::
-
-   For more information on connecting to your MongoDB deployment, see the :doc:`Connection Guide </connect>`.
+.. note /code-snippets/aggregation/agg.js deleted - check if file used elsewhere
 
 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 :manual:`$match </reference/operator/aggregation/match/>` stage to filter for documents whose
-  ``categories`` array field contains the element ``Bakery``.
-
-- A :manual:`$group </reference/operator/aggregation/group/>` stage to group the matching documents by the ``stars``
-  field, accumulating a count of documents for each distinct value of ``stars``.
-
-.. literalinclude:: /code-snippets/aggregation/agg.js
-   :start-after: begin aggregation
-   :end-before: end aggregation
-   :language: javascript
-   :dedent:
-
-This example produces the following output:
-
-.. code-block:: json
-   :copyable: false
-
-   { _id: 4, count: 2 }
-   { _id: 3, count: 1 }
-   { _id: 5, count: 1 }
-
-For more information, see the `aggregate() API documentation <{+api+}/classes/Collection.html#aggregate>`__.
-
-.. _node-aggregation-tutorials-landing:
-.. _node-aggregation-tutorials:
-
-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
-<https://www.practical-mongodb-aggregations.com/>`__ 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
-   :ref:`node-aggregation` guide.
-
-.. _node-agg-tutorial-template-app:
-
-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 :ref:`node-get-started-download-and-install` and
-   :ref:`node-get-started-create-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:
-
-.. literalinclude:: /includes/aggregation/template-app.js
-   :language: javascript
-   :copyable: true
+.. note::
+  
+   This example uses the ``sample_restaurants.restaurants`` collection
+   from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+   free MongoDB Atlas cluster and load the sample datasets, see the :ref:`Get Started <node-get-started>` guide.
 
-.. important::
+The following code example produces a count of the number of bakeries in each borough
+of New York City. To do so, the aggregation pipeline uses the following aggregation stages:
 
-   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.
+- A :manual:`$match </reference/operator/aggregation/match/>` stage to filter
+  for documents whose ``cuisine`` field contains the element ``Bakery``.
 
-   If you attempt to run the code without making any changes, you will
-   encounter a connection error.
+- A :manual:`$group </reference/operator/aggregation/group/>` stage to group the
+  matching documents by the ``borough`` field, accumulating a count of documents
+  for each distinct value in the ``borough`` field.
 
-For every tutorial, you must replace the connection string placeholder with
-your deployment's connection string.
+.. io-code-block::
 
-.. tip::
-   
-   To learn how to locate your deployment's connection string, see the
-   :ref:`node-get-started-connection-string` step of the Quick Start guide.
+   .. input:: /code-snippets/aggregation/agg.js
+      :start-after: begin aggregation
+      :end-before: end aggregation
+      :language: javascript
+      :dedent:
 
-For example, if your connection string is
-``"mongodb+srv://mongodb-example:27017"``, your connection string assignment resembles
-the following:
+   .. output::
+      :language: console
+      :copyable: false
+      :visible: false
 
-.. code-block:: javascript
-   :copyable: false
+      { _id = Bronx, Count = 71 }
+      { _id = Brooklyn, Count = 173 }
+      { _id = Staten Island, Count = 20 }
+      { _id = Missing, Count = 2 }
+      { _id = Manhattan, Count = 221 }
+      { _id = Queens, Count = 204 }
 
-   const uri = "mongodb+srv://mongodb-example:27017";
+Additional information
+----------------------
 
-To run the completed file after you modify the template for a
-tutorial, run the following command in your shell:
+MongoDB Server Manual
+~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: bash
+To view a full list of expression operators, see 
+:manual:`Aggregation Operators </reference/operator/aggregation/>`.
 
-   node agg_tutorial.js
+To learn more about assembling an aggregation pipeline and view examples, see
+:manual:`Aggregation Pipeline </core/aggregation-pipeline/>`.
 
-Available Tutorials
-~~~~~~~~~~~~~~~~~~~
+To learn more about creating pipeline stages and view examples, see 
+:manual:`Aggregation Stages </reference/operator/aggregation-pipeline/>`.
 
-- :ref:`node-aggregation-filtered-subset`
-- :ref:`node-aggregation-group-total`
-- :ref:`node-aggregation-arrays`
-- :ref:`node-aggregation-one-to-one`
-- :ref:`node-aggregation-multi-field`
+To learn about explaining MongoDB aggregation operations, see
+:manual:`Explain Results </reference/explain-results/>` and
+:manual:`Query Plans </core/query-plans/>`.
 
-Additional Examples
-~~~~~~~~~~~~~~~~~~~
+API Documentation
+~~~~~~~~~~~~~~~~~
 
-To view step-by-step explanations of common aggregation tasks, see the
-:ref:`node-aggregation-tutorials-landing`.
+For more information about the aggregation operations discussed in this guide, see the
+following API documentation:
 
-You can find another aggregation pipeline example in the `Aggregation
-Framework with Node.js Tutorial
-<https://www.mongodb.com/blog/post/quick-start-nodejs--mongodb--how-to-analyze-data-using-the-aggregation-framework>`_
-blog post on the MongoDB website.
+- `Aggregate() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.Aggregate.html>`__
+- `AggregateOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.AggregateOptions.html>`__
+- `Group()
+  <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineStageDefinitionBuilder.Group.html>`__
+- `Match() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineStageDefinitionBuilder.Match.html>`__
+- `Where() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.Where.html>`__
+- `GroupBy() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.GroupBy.html>`__
+- `Select() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.Select.html>`__
diff --git a/source/code-snippets/aggregation/agg.js b/source/code-snippets/aggregation/agg.js
@@ -6,28 +6,11 @@ const uri = process.env.MONGDODB_URI;
 const client = new MongoClient(uri);
 
 async function run() {
-    // begin data insertion
-    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);
-    // end data insertion
-
     // begin aggregation
     // Define an aggregation pipeline with a match stage and a group stage
     const pipeline = [
-        { $match: { categories: "Bakery" } },
-        { $group: { _id: "$stars", count: { $sum: 1 } } }
+        { $match: { cuisine: "Bakery" } },
+        { $group: { _id: "$borough", count: { $sum: 1 } } }
     ];
 
     // Execute the aggregation
