DOCS-13620 Let variables in update

source/includes/let-example-create-flavors.rst

@@ -0,0 +1,9 @@
+Create a collection ``cakeFlavors``:
+
+.. code-block:: javascript
+
+   db.cakeFlavors.insert( [
+      { _id: 1, flavor: "chocolate" },
+      { _id: 2, flavor: "strawberry" },
+      { _id: 3, flavor: "cherry" }
+   ] )

source/includes/let-example-delete-flavors.rst

@@ -0,0 +1,4 @@
+.. include:: /includes/let-example-create-flavors.rst
+
+The following example defines a ``targetFlavor`` variable in ``let`` and
+uses the variable to delete the strawberry cake flavor:

source/includes/let-example-find-flavors.rst

@@ -0,0 +1,4 @@
+.. include:: /includes/let-example-create-flavors.rst
+
+The following example defines a ``targetFlavor`` variable in ``let`` and
+uses the variable to retrieve the chocolate cake flavor:

source/includes/let-example-find-modify-flavors.rst

@@ -0,0 +1,4 @@
+.. include:: /includes/let-example-create-flavors.rst
+
+The following example defines a ``targetFlavor`` variable in ``let`` and
+uses the variable to change the cake flavor from cherry to orange:

source/includes/let-example-introduction.rst

@@ -0,0 +1,7 @@
+Use Variables in ``let``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.0
+
+To specify variables that can be accessed in the command, use the
+``let`` option.

source/includes/let-example-update-flavors.rst

@@ -0,0 +1,5 @@
+.. include:: /includes/let-example-create-flavors.rst
+
+The following example defines ``targetFlavor`` and ``newFlavor``
+variables in ``let`` and uses the variables to change the cake flavor
+from cherry to orange:

source/includes/let-syntax-generic.rst

@@ -0,0 +1,28 @@
+Specifies a document with a list of variables. This allows you to
+improve command readability by separating the variables from the query
+text. The document syntax is:
+
+.. code-block:: javascript
+   :copyable: false
+
+   { <variable_name_1>: <expression_1>,
+     ...,
+     <variable_name_n>: <expression_n> }
+
+The variable is set to the value returned by the expression, and cannot
+be changed afterwards.
+
+Examples:
+
+- ``{ targetTotal: 3000 }``, sets ``targetTotal`` to ``3000``.
+
+- ``{ totalCost: { $add: [ 125, 16, 765 ] } }``, sets ``totalCost`` to
+  ``906``.
+
+- ``{ myRecordingTime: "$$NOW" }``, sets ``myRecordingTime`` to the
+  current date and time returned by the :variable:`NOW` system
+  variable.
+
+To access the value of a variable in the command, use the double
+dollar sign prefix (``$$``) together with your variable name in the form
+``$$<variable_name>``. For example: ``$$targetTotal``.

source/reference/command/delete.txt

@@ -21,6 +21,10 @@ Definition
    collections </core/capped-collections>`. The remove methods provided
    by the MongoDB drivers use this command internally.
 
+   .. versionchanged:: 5.0
+
+   .. _delete-syntax:
+
    The :dbcommand:`delete` command has the following syntax:
 
    .. code-block:: javascript
@@ -38,7 +42,8 @@ Definition
             ...
          ],
          ordered: <boolean>,
-         writeConcern: { <write concern> }
+         writeConcern: { <write concern> },
+         let: <document> // Added in MongoDB 5.0
       }
 
    The command takes the following fields:
@@ -110,6 +115,20 @@ Definition
           .. versionadded:: 4.4
 
 
+      * - :ref:`let <delete-let-syntax>`
+
+        - document
+
+        - .. _delete-let-syntax:
+
+          Optional.
+
+          .. include:: /includes/let-syntax-generic.rst
+
+          For an example, see :ref:`delete-let-example`.
+
+          .. versionadded:: 5.0
+
 
    .. |operation| replace:: delete
 
@@ -414,6 +433,25 @@ To see the index used, run :dbcommand:`explain` on the operation:
       }
    )
 
+.. _delete-let-example:
+
+.. include:: /includes/let-example-introduction.rst
+
+For the syntax, see :ref:`let <delete-let-syntax>`.
+
+.. include:: /includes/let-example-delete-flavors.rst
+
+.. code-block:: javascript
+
+   db.runCommand( {
+      delete: db.cakeFlavors.getName(),
+      deletes: [ {
+         q: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
+         limit: 1
+      } ],
+      let : { targetFlavor: "strawberry" }
+   } )
+
 .. _delete-command-output:
 
 Output

source/reference/command/find.txt

@@ -40,6 +40,8 @@ Syntax
 
 The :dbcommand:`find` command has the following syntax:
 
+.. versionchanged:: 5.0
+
 .. code-block:: javascript
 
    db.runCommand(
@@ -66,7 +68,8 @@ The :dbcommand:`find` command has the following syntax:
          "awaitData": <bool>,
          "allowPartialResults": <bool>,
          "collation": <document>,
-         "allowDiskUse" : <bool>
+         "allowDiskUse" : <bool>,
+         "let": <document> // Added in MongoDB 5.0
       }
    )
 
@@ -396,6 +399,22 @@ The command accepts the following fields:
 
        .. versionadded:: 4.4
 
+
+
+   * - :ref:`let <find-let-syntax>`
+
+     - document
+
+     - .. _find-let-syntax:
+
+       Optional.
+
+       .. include:: /includes/let-syntax-generic.rst
+
+       For an example, see :ref:`find-let-example`.
+
+       .. versionadded:: 5.0
+
 .. _cmd-find-output:
 
 Output
@@ -611,4 +630,21 @@ The :binary:`~bin.mongo` shell provides the :method:`cursor.collation()` to
 specify :ref:`collation <collation>` for a
 :method:`db.collection.find()` operation.
 
+.. _find-let-example:
+
+.. include:: /includes/let-example-introduction.rst
+
+For the syntax, see :ref:`let <find-let-syntax>`.
+
+.. include:: /includes/let-example-find-flavors.rst
+
+.. code-block:: javascript
+
+   db.cakeFlavors.runCommand( {
+      find: db.cakeFlavors.getName(),
+      filter: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
+      let : { targetFlavor: "chocolate" }
+   } )
+
+
 .. seealso:: :ref:`3.2-driver-compatibility`

source/reference/command/findAndModify.txt

@@ -24,6 +24,8 @@ Definition
    modifications made on the update. To return the document with the
    modifications made on the update, use the ``new`` option.
 
+   .. versionchanged:: 5.0
+
    The command has the following syntax:
 
    .. code-block:: none
@@ -42,7 +44,8 @@ Definition
         collation: <document>,
         arrayFilters: <array>,
         hint: <document|string>,
-        comment: <any>
+        comment: <any>,
+        let: <document> // Added in MongoDB 5.0
       }
 
    The :dbcommand:`findAndModify` command takes the following
@@ -250,6 +253,19 @@ Definition
 
           .. versionadded:: 4.4
 
+      * - :ref:`let <findAndModify-let-syntax>`
+
+        - document
+
+        - .. _findAndModify-let-syntax:
+
+          Optional.
+
+          .. include:: /includes/let-syntax-generic.rst
+
+          For an example, see :ref:`findAndModify-let-example`.
+
+          .. versionadded:: 5.0
 
 Output
 ------
@@ -1041,4 +1057,22 @@ To see the index used, run :dbcommand:`explain` on the operation:
       }
    )
 
+.. _findAndModify-let-example:
+
+.. include:: /includes/let-example-introduction.rst
+
+For the syntax, see :ref:`let <findAndModify-let-syntax>`.
+
+.. include:: /includes/let-example-find-modify-flavors.rst
+
+.. code-block:: javascript
+
+   db.cakeFlavors.runCommand( {
+      findAndModify: db.cakeFlavors.getName(),
+      query: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
+      update: { flavor: "orange" },
+      let: { targetFlavor: "cherry" }
+   } )
+
+
 .. seealso:: :ref:`perform-findAndModify-linearizable-reads`

source/reference/command/update.txt

@@ -34,7 +34,7 @@ Definition
 Syntax
 ------
 
-.. versionchanged:: 4.2
+.. versionchanged:: 5.0
 
 The :dbcommand:`update` command has the following syntax:
 
@@ -47,6 +47,7 @@ The :dbcommand:`update` command has the following syntax:
             {
               q: <query>,
               u: <document or pipeline>,
+              c: <document> // Added in MongoDB 5.0,
               upsert: <boolean>,
               multi: <boolean>,
               collation: <document>,
@@ -58,7 +59,8 @@ The :dbcommand:`update` command has the following syntax:
          ordered: <boolean>,
          writeConcern: { <write concern> },
          bypassDocumentValidation: <boolean>,
-         comment: <any>
+         comment: <any>,
+         let: <document> // Added in MongoDB 5.0
       }
    )
 
@@ -139,6 +141,20 @@ The command takes the following fields:
        .. versionadded:: 4.4
 
 
+   * - :ref:`let <update-let-syntax>`
+
+     - document
+
+     - .. _update-let-syntax:
+
+       Optional.
+
+       .. include:: /includes/let-syntax-generic.rst
+
+       For an example, see :ref:`update-variables-example`.
+
+       .. versionadded:: 5.0
+
 .. _update-statement-documents:
 
 Update Statements
@@ -188,6 +204,20 @@ Each document contains the following fields:
 
        For details, see :ref:`update-command-behaviors`.
 
+   * - :ref:`c <update-command-c>`
+
+     - document
+
+     - .. _update-command-c:
+
+       Optional.
+
+       .. include:: /includes/let-syntax-generic.rst
+
+       For an example, see :ref:`update-variables-example`.
+
+       .. versionadded:: 5.0
+
    * - :ref:`upsert <update-command-upsert>`
 
      - boolean
@@ -1052,6 +1082,45 @@ To see the index used, run :dbcommand:`explain` on the operation:
 
 The :dbcommand:`explain` does not modify the documents.
 
+.. _update-variables-example:
+
+Use Variables in ``let`` Option or ``c`` Field
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 5.0
+
+Variables can be defined in the :ref:`let <update-let-syntax>` option or
+the :ref:`c <update-command-c>` field and accessed in the ``updates``
+array.
+
+.. include:: /includes/let-example-update-flavors.rst
+
+.. code-block:: javascript
+
+   db.runCommand( {
+      update: db.cakeFlavors.getName(),
+      updates: [
+         { q: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
+           u: [ { $set: { flavor: "$$newFlavor" } } ] }
+      ],
+      let : { targetFlavor: "cherry", newFlavor: "orange" }
+   } )
+
+The next example defines ``targetFlavor`` and ``newFlavor`` variables in
+``c`` and uses the variables to change the cake flavor from chocolate to
+vanilla:
+
+.. code-block:: javascript
+
+   db.runCommand( {
+      update: db.cakeFlavors.getName(),
+      updates: [
+         { q: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
+           u: [ { $set: { flavor: "$$newFlavor" } } ],
+           c: { targetFlavor: "chocolate", newFlavor: "vanilla" } }
+       ]
+   } )
+
 .. _update-command-output:
 
 Output