DOCS-14890 refactor start of aggregation pipeline page (#6056)

source/aggregation.txt

@@ -10,39 +10,41 @@ Aggregation
    :depth: 1
    :class: singlecol
 
-Aggregation operations process data records and return computed
-results. Aggregation operations group values from multiple documents
-together, and can perform a variety of operations on the grouped data
-to return a single result. MongoDB provides three ways to perform
-aggregation: the :ref:`aggregation pipeline
-<aggregation-framework>`, the :ref:`map-reduce function
-<aggregation-map-reduce>`, and :ref:`single purpose aggregation methods
-<single-purpose-agg-operations>`.
+Aggregation operations process multiple documents and return computed
+results. You can use aggregation operations to:
+
+- Group values from multiple documents together.
+
+- Perform operations on the grouped data to return a single result.
+
+- Analyze data changes over time.
+
+To perform aggregation operations, you can use:
+
+- :ref:`Aggregation pipelines <aggregation-framework>`
+
+- :ref:`Single purpose aggregation methods
+  <single-purpose-agg-operations>`
+
+- :ref:`Map-reduce functions <aggregation-map-reduce>`
 
 .. _aggregation-framework:
 
-Aggregation Pipeline
---------------------
+Aggregation Pipelines
+---------------------
 
-MongoDB's :doc:`aggregation framework
-</core/aggregation-pipeline>` is modeled on the concept of data
-processing pipelines. Documents enter a multi-stage pipeline that
-transforms the documents into an aggregated result. For example:
+.. include:: /includes/aggregation-pipeline-introduction.rst
 
-.. code-block:: javascript
+Aggregation Pipeline Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-   db.orders.aggregate([
-      { $match: { status: "A" } },
-      { $group: { _id: "$cust_id", total: { $sum: "$amount" } } }
-   ])
+.. include:: /includes/aggregation-pipeline-example.rst
 
-**First Stage**: The :pipeline:`$match` stage filters the documents by
-the ``status`` field and passes to the next stage those documents that
-have ``status`` equal to ``"A"``.
+For a runnable example, see :ref:`Complete Aggregation Pipeline
+Example <aggregation-pipeline-example>`.
 
-**Second Stage**: The :pipeline:`$group` stage groups the documents by
-the ``cust_id`` field to calculate the sum of the amount for each
-unique ``cust_id``.
+Aggregation Pipeline Stages and Operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The most basic pipeline stages provide *filters* that operate like
 queries and *document transformations* that modify the form

source/core/aggregation-pipeline.txt

@@ -1,4 +1,4 @@
-.. _aggregation-top-level-server:
+.. _aggregation-pipeline:
 
 ====================
 Aggregation Pipeline
@@ -12,66 +12,92 @@ Aggregation Pipeline
    :depth: 1
    :class: singlecol
 
-The aggregation pipeline is a framework for data aggregation modeled
-on the concept of data processing pipelines. Documents enter a
-multi-stage pipeline that transforms the documents into aggregated
-results. For example:
+.. include:: /includes/aggregation-pipeline-introduction.rst
+
+.. _aggregation-pipeline-example:
+
+Complete Aggregation Pipeline Example
+-------------------------------------
+
+Create the following collection that contains orders for products:
 
 .. code-block:: javascript
 
-   db.orders.aggregate([
-      { $match: { status: "A" } },
-      { $group: { _id: "$cust_id", total: { $sum: "$amount" } } }
-   ])
+   db.orders.insertMany( [
+      { _id: 0, productName: "Steel beam", status: "new", quantity: 10 },
+      { _id: 1, productName: "Steel beam", status: "urgent", quantity: 20 },
+      { _id: 2, productName: "Steel beam", status: "urgent", quantity: 30 },
+      { _id: 3, productName: "Iron rod", status: "new", quantity: 15 },
+      { _id: 4, productName: "Iron rod", status: "urgent", quantity: 50 },
+      { _id: 5, productName: "Iron rod", status: "urgent", quantity: 10 }
+   ] )
 
-**First Stage**: The :pipeline:`$match` stage filters the documents by
-the ``status`` field and passes to the next stage those documents that
-have ``status`` equal to ``"A"``.
+.. include:: /includes/aggregation-pipeline-example.rst
 
-**Second Stage**: The :pipeline:`$group` stage groups the documents by
-the ``cust_id`` field to calculate the sum of the amount for each
-unique ``cust_id``.
+Example output:
 
-.. _aggregation-pipeline:
+.. code-block:: javascript
+   :copyable: false
 
-Pipeline
---------
+   [
+      { _id: 'Steel beam', sumQuantity: 50 },
+      { _id: 'Iron rod', sumQuantity: 60 }
+   ]
 
-The MongoDB aggregation pipeline consists of :ref:`stages
-<aggregation-pipeline-operator-reference>`. Each stage transforms the
-documents as they pass through the pipeline. Pipeline stages do not need
-to produce one output document for every input document. For example,
-some stages may generate new documents or filter out documents.
+.. seealso::
 
-Pipeline stages can appear multiple times in the pipeline with the
-exception of :pipeline:`$out`, :pipeline:`$merge`, and
-:pipeline:`$geoNear` stages. For a list
-of all available stages, see
-:ref:`aggregation-pipeline-operator-reference`.
+   - :doc:`/tutorial/aggregation-with-user-preference-data`
+   - :doc:`/tutorial/aggregation-zip-code-data-set`
+   - :doc:`/tutorial/update-documents-with-aggregation-pipeline`
 
 MongoDB provides the :method:`db.collection.aggregate()` method in the
 :binary:`~bin.mongo` shell and the :dbcommand:`aggregate` command to
-run the aggregation pipeline. 
+run the aggregation pipeline.
 
-For example usage of the aggregation pipeline, consider
-:doc:`/tutorial/aggregation-with-user-preference-data` and
-:doc:`/tutorial/aggregation-zip-code-data-set`.
+.. _aggregation-pipeline-stages:
 
-Starting in MongoDB 4.2, you can use the aggregation pipeline for
-updates in:
+Aggregation Pipeline Stages
+---------------------------
 
-.. include:: /includes/table-update-with-aggregation-availability.rst
+An aggregation pipeline consists of one or more :ref:`stages
+<aggregation-pipeline-operator-reference>` that process documents:
+
+- Each stage transforms the documents as they pass through the pipeline.
 
-.. seealso::
+- A stage does not have to output one document for every input
+  document. For example, some stages may produce new documents or
+  filter out documents.
 
-   :doc:`/tutorial/update-documents-with-aggregation-pipeline`
+- The same stage can appear multiple times in the pipeline with these
+  stage exceptions: :pipeline:`$out`, :pipeline:`$merge`, and
+  :pipeline:`$geoNear`.
+
+- For all available stages, see
+  :ref:`aggregation-pipeline-operator-reference`.
+
+Run an Aggregation Pipeline
+---------------------------
+
+To run an aggregation pipeline, use:
+
+- :method:`db.collection.aggregate()` or
 
-.. _aggregation-pipeline-expressions:
+- :dbcommand:`aggregate`
+
+Update Documents Using an Aggregation Pipeline
+----------------------------------------------
+
+Starting in MongoDB 4.2, you can use the aggregation pipeline to update
+documents using these methods:
+
+.. include:: /includes/table-update-with-aggregation-availability.rst
 
+ .. _aggregation-pipeline-expressions:
+
 Pipeline Expressions
 --------------------
 
-Some pipeline stages take a pipeline expression as the operand.
+Some pipeline stages accept a pipeline expression as the operand.
 Pipeline expressions specify the transformation to apply to the input
 documents. Expressions have a :doc:`document </core/document>`
 structure and can contain other :ref:`expression

source/includes/aggregation-pipeline-example.rst

@@ -0,0 +1,24 @@
+The following aggregation pipeline example contains two :ref:`stages
+<aggregation-pipeline-operator-reference>` and returns the total
+quantity of urgent orders for each product:
+
+.. code-block:: javascript
+
+   db.orders.aggregate( [
+      { $match: { status: "urgent" } },
+      { $group: { _id: "$productName", sumQuantity: { $sum: "$quantity" } } }
+   ] )
+
+The :pipeline:`$match` stage:
+
+- Filters the documents to those with a ``status`` of ``urgent``.
+
+- Outputs the filtered documents to the :pipeline:`$group` stage.
+
+The :pipeline:`$group` stage:
+
+- Groups the input documents by ``productName``.
+
+- Uses :group:`$sum` to calculate the total ``quantity`` for each
+  ``productName``, which is stored in the ``sumQuantity`` field returned
+  by the aggregation pipeline.

source/includes/aggregation-pipeline-introduction.rst

@@ -0,0 +1,12 @@
+An aggregation pipeline consists of one or more :ref:`stages
+<aggregation-pipeline-operator-reference>` that process documents:
+
+- Each stage performs an operation on the input documents.
+  For example, a stage can filter documents, group documents, and
+  calculate values.
+
+- The documents that are output from one stage are input to the next
+  stage.
+
+- An aggregation pipeline can return results for groups of documents.
+  For example, return the total, average, maximum, and minimum values.

source/includes/table-update-with-aggregation-availability.rst

@@ -13,7 +13,6 @@
 
      - | :ref:`db.collection.updateOne() <updateOne-example-agg>`
        | :ref:`db.collection.updateMany() <updateMany-example-agg>`
-       | :ref:`db.collection.update() <update-example-agg>`
 
        | :ref:`Bulk.find.update() <example-bulk-find-update-agg>`
        | :ref:`Bulk.find.updateOne() <example-bulk-find-update-one-agg>`