DOCSP-50497 fixing git rebases and uploading changes to agg pages

Author: mballard-mdb

snooty.toml

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

source/aggregation.txt

@@ -14,22 +14,29 @@ Aggregation
 
 .. contents:: On this page
    :local:
+
    :backlinks: none
    :depth: 2
    :class: singlecol
 
+.. toctree::
+
+   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 MongoDB Node.js 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
+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.
+
+To learn more about the aggregation stages supported by the Node.js Driver, see :ref:`Aggregation Stages <node-aggregation-pipeline-stages>`.
 
 .. _node-aggregation-tutorials:
 
@@ -42,114 +49,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>`
+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. 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 }
+- 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. 
 
-For more information, see the `aggregate() API documentation <{+api+}/classes/Collection.html#aggregate>`__.
+Additional information
+----------------------
 
-Additional Examples
-~~~~~~~~~~~~~~~~~~~
+To view a full list of expression operators, see 
+:manual:`Aggregation Operators </reference/operator/aggregation/>`.
 
-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.
+To learn about explaining MongoDB aggregation operations, see
+:manual:`Explain Results </reference/explain-results/>` and
+:manual:`Query Plans </core/query-plans/>`.