[v6.17] DOCSP-50497 Node Aggregation Standardization (#1176)

snooty.toml

@@ -11,9 +11,9 @@ toc_landing_pages = [
     "/connect",
     "/security",
     "/security/authentication",
-    "/aggregation-tutorials",
     "/data-formats",
     "/connect/connection-options",
+    "/aggregation",
     "/crud",
     "/crud/query",
     "crud/update",

source/aggregation.txt

@@ -1,9 +1,9 @@
 .. _node-aggregation:
 .. _nodejs-aggregation:
 
-===========
-Aggregation
-===========
+======================
+Aggregation Operations
+======================
 
 .. facet::
    :name: genre
@@ -18,18 +18,27 @@ Aggregation
    :depth: 2
    :class: singlecol
 
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   Pipeline Stages </aggregation/pipeline-stages>
+
 .. _nodejs-aggregation-overview:
 
 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 {+driver-long+} to perform
+**aggregation operations**.
+
+Aggregation operations process data in your MongoDB collections and return
+computed 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.
 
-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.
+To learn more about the aggregation stages supported by the {+driver-short+},
+see :ref:`node-aggregation-pipeline-stages`.
 
 .. _node-aggregation-tutorials:
 
@@ -42,114 +51,67 @@ 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 :manual:`limitations </core/aggregation-pipeline-limits/>`:
-
-- 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``.
-
-References
-~~~~~~~~~~
-
-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>`.
-
-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>`__.
-
-Additional Examples
-~~~~~~~~~~~~~~~~~~~
-
-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.
+The aggregation pipeline is similar to an automobile factory assembly line. An
+assembly line 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 assembles
+a separate part. The result is a transformed final product, the finished car.
+
+The *aggregation pipeline* is the assembly line, the *aggregation stages* are
+the assembly stations, the *expression operators* are the specialized tools, and
+the *aggregated result* is the finished product.
+
+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. If required,
+  you can exceed this limit by enabling the `AllowDiskUse
+  <https://mongodb.github.io/node-mongodb-native/6.17/interfaces/AggregateOptions.html#allowDiskUse>`__
+  property of the ``AggregateOptions`` object that you pass to the
+  ``aggregate()`` method. 
+
+Additional information
+----------------------
+
+To view a full list of expression operators, see :manual:`Aggregation Operators
+</reference/operator/aggregation/>` in the {+mdb-server+} manual.
+
+To learn about explaining MongoDB aggregation operations, see :manual:`Explain
+Results </reference/explain-results/>` and :manual:`Query Plans
+</core/query-plans/>` in the {+mdb-server+} manual.