(DOCSP-32356): Revamp Updates with Aggregation page for the top 250 project (#4793)

* Draft procedures

* Add OTP and missing image

* Add more links and update headers

* Adjust heading depth

* Substitutions apparently don't work with links

* Incorporate review feedback

* Remove images

* Incorporate review feedback

* Incorporate review feedback

* Arbitrary commit to trigger a staging rebuild

Author: dacharyc

source/includes/aggregation/update-aggregation-stages.rst

@@ -0,0 +1,6 @@
+- :pipeline:`$addFields`
+- :pipeline:`$set`
+- :pipeline:`$project`
+- :pipeline:`$unset`
+- :pipeline:`$replaceRoot`
+- :pipeline:`$replaceWith`

source/tutorial/update-documents-with-aggregation-pipeline.txt

@@ -13,23 +13,142 @@ Updates with Aggregation Pipeline
 .. meta::
    :description: The following page provides examples of updates with aggregation pipelines.
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 Starting in MongoDB 4.2, you can use the aggregation pipeline for
-update operations. With the update operations, the aggregation
-pipeline can consist of the following stages:
+update operations. You can build and execute aggregation pipelines to 
+perform updates in `{+atlas+} <https://www.mongodb.com/docs/atlas>`__, 
+`MongoDB Compass <https://www.mongodb.com/docs/compass/>`__, 
+`MongoDB Shell <https://www.mongodb.com/docs/mongodb-shell/>`__, or 
+`Drivers <https://www.mongodb.com/docs/drivers/>`__.
+
+With the update operations, the aggregation pipeline can consist of the 
+following stages:
 
-- :pipeline:`$addFields`
-- :pipeline:`$set`
-- :pipeline:`$project`
-- :pipeline:`$unset`
-- :pipeline:`$replaceRoot`
-- :pipeline:`$replaceWith`
+.. include:: /includes/aggregation/update-aggregation-stages.rst
 
 Using the aggregation pipeline allows for a more expressive update
 statement, such as expressing conditional updates based on current
 field values or updating one field using the value of another field(s).
 
-Example 1
-----------
+Create an Update Aggregation Pipeline in Atlas
+----------------------------------------------
+
+You can use the {+atlas+} UI to build an aggregation pipeline to perform 
+updates. To create and execute aggregation pipelines in the
+{+atlas+} UI, you must have the 
+:authrole:`Project Data Access Read Only` role or higher.
+
+.. procedure::
+   :style: normal
+
+   .. step:: Access the Aggregation Pipeline Builder.
+
+      .. procedure::
+         :style: connected
+
+         .. step:: Select the database for the collection.
+
+            The main panel and :guilabel:`Namespaces` on the left side list the
+            collections in the database.
+
+         .. step:: Select the collection.
+
+            Select the collection on the left-hand side or in the main panel.
+            The main panel displays the :guilabel:`Find`, :guilabel:`Indexes`,
+            and :guilabel:`Aggregation` views.
+
+         .. step:: Select the Aggregation view.
+
+            When you first open the :guilabel:`Aggregation` view, Atlas
+            displays an empty aggregation pipeline.
+
+   .. step:: Create an aggregation pipeline to perform updates.
+
+      .. procedure::
+         :style: connected
+
+         .. step:: Select an aggregation stage.
+      
+            Select an aggregation stage from the :guilabel:`Select` 
+            drop-down menu in the bottom-left panel.
+            
+            The toggle to the right of the drop-down menu dictates whether 
+            the stage is enabled.
+
+            To perform updates with an aggregation, use one of 
+            these stages:
+
+            .. include:: /includes/aggregation/update-aggregation-stages.rst
+
+         .. step:: Fill in your aggregation stage.
+
+            Fill in your stage with the appropriate values. 
+            If :ref:`Comment Mode <pipeline-settings>` is enabled, the pipeline
+            builder provides syntactic guidelines for your selected stage. 
+            
+            As you modify your stage, Atlas updates the preview documents on
+            the right based on the results of the current stage.
+
+            For examples of what you might include in your aggregation stage,
+            see the :ref:`examples <agg-updates-examples>` on this page.
+
+            Add stages as needed. For more information on creating aggregation
+            pipelines in Atlas, refer to :ref:`agg-pipeline-create`.
+
+   .. step:: Export the aggregation pipeline.
+
+      .. procedure::
+         :style: connected
+
+         .. step:: Click Export to Language.
+
+            You can find this button at the top of the pipeline builder.
+
+         .. step:: Select your desired export language.
+
+            In the :guilabel:`Export Pipeline To` menu, select your desired
+            language.
+
+            The :guilabel:`My Pipeline` pane on the left displays your
+            pipeline in |mdb-shell| syntax. You can copy this directly to execute
+            your pipeline in the |mdb-shell|.
+
+            The pane on the right displays your pipeline in the selected
+            language. Select your preferred language.
+
+         .. step:: Select options, if desired.
+
+            *(Optional)*: Check the :guilabel:`Include Import Statements` option
+            to include the required import statements for the language selected.
+
+            *(Optional)*: Check the :guilabel:`Include Driver Syntax` option
+            to include Driver-specific code to:
+            
+            - Initialize the client
+            - Specify the database and collection 
+            - Perform the aggregation operation
+
+         .. step:: Copy the pipeline.
+
+            Click the :guilabel:`Copy` button at the top-right of the pipeline
+            to copy the pipeline for the selected language to your clipboard.
+            Paste the copied pipeline into your application.
+
+.. _agg-updates-examples:
+
+Examples
+--------
+
+The following examples demonstrate how to use the aggregation pipeline
+stages ``$set``, ``$replaceRoot``, and ``$addFields`` to perform updates.
+
+updateOne with $set
+~~~~~~~~~~~~~~~~~~~
 
 Create an example ``students`` collection (if the collection does
 not currently exist, insert operations will create the collection):
@@ -68,8 +187,8 @@ To verify the update, you can query the collection:
 
    db.students.find().pretty()
 
-Example 2
-----------
+updateMany with $replaceRoot and $set
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Create an example ``students2`` collection (if the collection does not
 currently exist, insert operations will create the collection):
@@ -125,8 +244,8 @@ To verify the update, you can query the collection:
 
    db.students2.find()
 
-Example 3
----------
+updateMany with $set
+~~~~~~~~~~~~~~~~~~~~
 
 Create an example ``students3`` collection (if the collection does not
 currently exist, insert operations will create the collection):
@@ -186,8 +305,8 @@ To verify the update, you can query the collection:
 
    db.students3.find()
 
-Example 4
----------
+updateOne with $set
+~~~~~~~~~~~~~~~~~~~
 
 Create an example ``students4`` collection (if the collection does
 not currently exist, insert operations will create the collection):
@@ -223,8 +342,8 @@ To verify the update, query the collection:
 
    db.students4.find()
 
-Example 5
----------
+updateMany with $addFields
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Create an example ``temperatures`` collection that contains
 temperatures in Celsius (if the collection does not currently exist,
@@ -276,7 +395,7 @@ To verify the update, you can query the collection:
    db.temperatures.find()
 
 Additional Examples
--------------------
+~~~~~~~~~~~~~~~~~~~
 
 See also the various update method pages for additional examples: