DOCSP-14577 Let variables in aggregation expressions

source/includes/let-example-introduction.rst

@@ -1,7 +1,9 @@
-Use Variables in ``let``
-~~~~~~~~~~~~~~~~~~~~~~~~
-
 .. versionadded:: 5.0
 
-To specify variables that can be accessed in the command, use the
-``let`` option.
+To define variables that you can access elsewhere in the command, use
+the |let-option| option.
+
+.. note::
+
+   To filter results using a variable, you must access the variable
+   within the :query:`$expr` operator.

source/includes/let-variables-aggregate-syntax-note.rst

@@ -0,0 +1,5 @@
+.. note::
+
+   To use a variable to filter results in a pipeline :pipeline:`$match`
+   stage, you must access the variable within the :query:`$expr`
+   operator.

source/includes/let-variables-match-note.rst

@@ -0,0 +1,8 @@
+To define variables that you can access elsewhere in the command, use
+the |let-option| option.
+
+.. note::
+
+   To filter results using a variable in a pipeline :pipeline:`$match`
+   stage, you must access the variable within the :query:`$expr`
+   operator.

source/includes/let-variables-syntax-note.rst

@@ -0,0 +1,4 @@
+.. note::
+
+   To use a variable to filter results, you must access the variable
+   within the :query:`$expr` operator.

source/includes/let-variables-syntax.rst

@@ -14,17 +14,6 @@ The document syntax is:
 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/aggregate.txt

@@ -241,7 +241,10 @@ arguments:
 
        .. include:: /includes/let-variables-syntax.rst
 
-       For an example, see :ref:`aggregate-let-example`.
+       .. include:: /includes/let-variables-aggregate-syntax-note.rst
+
+       For a complete MQL example using ``let`` and variables, see
+       :ref:`aggregate-let-example`.
 
        .. versionadded:: 5.0
 
@@ -566,8 +569,9 @@ Use Variables in ``let``
 
 .. versionadded:: 5.0
 
-To specify variables that can be accessed elsewhere in the command, use
-the :ref:`let <aggregate-let-option>` option.
+.. |let-option| replace:: :ref:`let <aggregate-let-option>`
+
+.. include:: /includes/let-variables-match-note.rst
 
 .. include:: /includes/let-variables-example.rst
 

source/reference/command/delete.txt

@@ -125,7 +125,10 @@ Definition
 
           .. include:: /includes/let-variables-syntax.rst
 
-          For an example, see :ref:`delete-let-example`.
+          .. include:: /includes/let-variables-syntax-note.rst
+
+          For a complete MQL example using ``let`` and variables, see
+          see :ref:`delete-let-example`.
 
           .. versionadded:: 5.0
 
@@ -435,9 +438,12 @@ To see the index used, run :dbcommand:`explain` on the operation:
 
 .. _delete-let-example:
 
-.. include:: /includes/let-example-introduction.rst
+Use Variables in ``let``
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-For the syntax, see :ref:`let <delete-let-syntax>`.
+.. |let-option| replace:: :ref:`let <delete-let-syntax>`
+
+.. include:: /includes/let-example-introduction.rst
 
 .. include:: /includes/let-example-delete-flavors.rst
 

source/reference/command/find.txt

@@ -412,7 +412,10 @@ The command accepts the following fields:
 
        .. include:: /includes/let-variables-syntax.rst
 
-       For an example, see :ref:`find-let-example`.
+       .. include:: /includes/let-variables-syntax-note.rst
+
+       For a complete MQL example using ``let`` and variables, see
+       :ref:`find-let-example`.
 
        .. versionadded:: 5.0
 
@@ -633,9 +636,12 @@ specify :ref:`collation <collation>` for a
 
 .. _find-let-example:
 
-.. include:: /includes/let-example-introduction.rst
+Use Variables in ``let``
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-For the syntax, see :ref:`let <find-let-syntax>`.
+.. |let-option| replace:: :ref:`let <find-let-syntax>`
+
+.. include:: /includes/let-example-introduction.rst
 
 .. include:: /includes/let-example-find-flavors.rst
 

source/reference/command/findAndModify.txt

@@ -269,7 +269,10 @@ Definition
 
           .. include:: /includes/let-variables-syntax.rst
 
-          For an example, see :ref:`findAndModify-let-example`.
+          .. include:: /includes/let-variables-syntax-note.rst
+
+          For a complete MQL example using ``let`` and variables, see
+          :ref:`findAndModify-let-example`.
 
           .. versionadded:: 5.0
 
@@ -1014,9 +1017,12 @@ To see the index used, run :dbcommand:`explain` on the operation:
 
 .. _findAndModify-let-example:
 
-.. include:: /includes/let-example-introduction.rst
+Use Variables in ``let``
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-For the syntax, see :ref:`let <findAndModify-let-syntax>`.
+.. |let-option| replace:: :ref:`let <findAndModify-let-syntax>`
+
+.. include:: /includes/let-example-introduction.rst
 
 .. include:: /includes/let-example-find-modify-flavors.rst
 

source/reference/command/update.txt

@@ -150,7 +150,7 @@ The command takes the following fields:
 
        .. include:: /includes/let-variables-syntax.rst
 
-       For an example, see :ref:`update-variables-example`.
+       For a complete MQL example, see :ref:`update-variables-example`.
 
        .. versionadded:: 5.0
 
@@ -213,7 +213,10 @@ Each document contains the following fields:
 
        .. include:: /includes/let-variables-syntax.rst
 
-       For an example, see :ref:`update-variables-example`.
+       .. include:: /includes/let-variables-syntax-note.rst
+
+       For a complete MQL example using ``let`` and variables, see
+       :ref:`update-variables-example`.
 
        .. versionadded:: 5.0
 
@@ -1089,6 +1092,11 @@ 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.
 
+.. note::
+
+   To filter results using a variable, you must access the variable
+   within the :query:`$expr` operator.
+
 .. include:: /includes/let-example-update-flavors.rst
 
 .. code-block:: javascript

source/reference/method/db.collection.aggregate.txt

@@ -219,7 +219,9 @@ Definition
 
           .. include:: /includes/let-variables-syntax.rst
 
-          For an example, see
+          .. include:: /includes/let-variables-aggregate-syntax-note.rst
+
+          For a complete MQL example using ``let`` and variables, see
           :ref:`db.collection.aggregate-let-example`.
 
           .. versionadded:: 5.0
@@ -632,8 +634,9 @@ Use Variables in ``let``
 
 .. versionadded:: 5.0
 
-To specify variables that can be accessed elsewhere in the command, use
-the :ref:`let <db.collection.aggregate-let-option>` option.
+.. |let-option| replace:: :ref:`let <db.collection.aggregate-let-option>`
+
+.. include:: /includes/let-variables-match-note.rst
 
 .. include:: /includes/let-variables-example.rst
 

source/reference/method/db.collection.findAndModify.txt

@@ -245,7 +245,9 @@ Definition
 
           .. include:: /includes/let-variables-syntax.rst
 
-          For an example, see
+          .. include:: /includes/let-variables-syntax-note.rst
+
+          For a complete MQL example using ``let`` and variables, see
           :ref:`db.collection.findAndModify-let-example`.
 
           .. versionadded:: 5.0
@@ -772,9 +774,12 @@ The operation returns the *updated* document:
 
 .. _db.collection.findAndModify-let-example:
 
-.. include:: /includes/let-example-introduction.rst
+Use Variables in ``let``
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-For the syntax, see :ref:`let <db.collection.findAndModify-let-syntax>`.
+.. |let-option| replace:: :ref:`let <db.collection.findAndModify-let-syntax>`
+
+.. include:: /includes/let-example-introduction.rst
 
 .. include:: /includes/let-example-find-modify-flavors.rst
 

source/reference/method/db.collection.remove.txt

@@ -110,7 +110,10 @@ Definition
 
           .. include:: /includes/let-variables-syntax.rst
 
-          For an example, see :ref:`db.collection.remove-let-example`.
+          .. include:: /includes/let-variables-syntax-note.rst
+
+          For a complete MQL example using ``let`` and variables, see
+          :ref:`db.collection.remove-let-example`.
 
           .. versionadded:: 5.0
 
@@ -271,9 +274,12 @@ option:
 
 .. _db.collection.remove-let-example:
 
-.. include:: /includes/let-example-introduction.rst
+Use Variables in ``let``
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-For the syntax, see :ref:`let <db.collection.remove-let-syntax>`.
+.. |let-option| replace:: :ref:`let <db.collection.remove-let-syntax>`
+
+.. include:: /includes/let-example-introduction.rst
 
 .. include:: /includes/let-example-delete-flavors.rst
 

source/reference/method/db.collection.update.txt

@@ -218,7 +218,10 @@ parameters:
 
        .. include:: /includes/let-variables-syntax.rst
 
-       For an example, see :ref:`db.collection.update-let-example`.
+       .. include:: /includes/let-variables-syntax-note.rst
+
+       For a complete MQL example using ``let`` and variables, see
+       :ref:`db.collection.update-let-example`.
 
        .. versionadded:: 5.0
 
@@ -1462,9 +1465,12 @@ does not modify the documents.
 
 .. _db.collection.update-let-example:
 
-.. include:: /includes/let-example-introduction.rst
+Use Variables in ``let``
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-For the syntax, see :ref:`let <db.collection.update-let-syntax>`.
+.. |let-option| replace:: :ref:`let <db.collection.update-let-syntax>`
+
+.. include:: /includes/let-example-introduction.rst
 
 .. include:: /includes/let-example-update-flavors.rst