From 0bb1853b437931fea8e965f6fb5d82eb19f5107c Mon Sep 17 00:00:00 2001 From: jason-price-mongodb Date: Fri, 25 Jun 2021 14:55:00 -0700 Subject: [PATCH] DOCSP-14577 Let variables in aggregation expressions --- source/includes/let-example-introduction.rst | 12 +++++++----- .../includes/let-variables-aggregate-syntax-note.rst | 5 +++++ source/includes/let-variables-match-note.rst | 8 ++++++++ source/includes/let-variables-syntax-note.rst | 4 ++++ source/includes/let-variables-syntax.rst | 11 ----------- source/reference/command/aggregate.txt | 10 +++++++--- source/reference/command/delete.txt | 12 +++++++++--- source/reference/command/find.txt | 12 +++++++++--- source/reference/command/findAndModify.txt | 12 +++++++++--- source/reference/command/update.txt | 12 ++++++++++-- source/reference/method/db.collection.aggregate.txt | 9 ++++++--- .../reference/method/db.collection.findAndModify.txt | 11 ++++++++--- source/reference/method/db.collection.remove.txt | 12 +++++++++--- source/reference/method/db.collection.update.txt | 12 +++++++++--- 14 files changed, 100 insertions(+), 42 deletions(-) create mode 100644 source/includes/let-variables-aggregate-syntax-note.rst create mode 100644 source/includes/let-variables-match-note.rst create mode 100644 source/includes/let-variables-syntax-note.rst diff --git a/source/includes/let-example-introduction.rst b/source/includes/let-example-introduction.rst index 035bfd6c8e1..350c4687d64 100644 --- a/source/includes/let-example-introduction.rst +++ b/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. \ No newline at end of file +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. \ No newline at end of file diff --git a/source/includes/let-variables-aggregate-syntax-note.rst b/source/includes/let-variables-aggregate-syntax-note.rst new file mode 100644 index 00000000000..c5a1d5d53cb --- /dev/null +++ b/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. \ No newline at end of file diff --git a/source/includes/let-variables-match-note.rst b/source/includes/let-variables-match-note.rst new file mode 100644 index 00000000000..f30e445ba0e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/source/includes/let-variables-syntax-note.rst b/source/includes/let-variables-syntax-note.rst new file mode 100644 index 00000000000..57f93f01a03 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/source/includes/let-variables-syntax.rst b/source/includes/let-variables-syntax.rst index 63aef3c27e0..f2371b703f5 100644 --- a/source/includes/let-variables-syntax.rst +++ b/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 ``$$``. For example: ``$$targetTotal``. \ No newline at end of file diff --git a/source/reference/command/aggregate.txt b/source/reference/command/aggregate.txt index 336e8466e8a..8e08b3aba7c 100644 --- a/source/reference/command/aggregate.txt +++ b/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 ` option. +.. |let-option| replace:: :ref:`let ` + +.. include:: /includes/let-variables-match-note.rst .. include:: /includes/let-variables-example.rst diff --git a/source/reference/command/delete.txt b/source/reference/command/delete.txt index 5e1ac15695a..9ed55b4eddd 100644 --- a/source/reference/command/delete.txt +++ b/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 `. +.. |let-option| replace:: :ref:`let ` + +.. include:: /includes/let-example-introduction.rst .. include:: /includes/let-example-delete-flavors.rst diff --git a/source/reference/command/find.txt b/source/reference/command/find.txt index a92c15b59f6..2b72bf9dd5d 100644 --- a/source/reference/command/find.txt +++ b/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 ` for a .. _find-let-example: -.. include:: /includes/let-example-introduction.rst +Use Variables in ``let`` +~~~~~~~~~~~~~~~~~~~~~~~~ -For the syntax, see :ref:`let `. +.. |let-option| replace:: :ref:`let ` + +.. include:: /includes/let-example-introduction.rst .. include:: /includes/let-example-find-flavors.rst diff --git a/source/reference/command/findAndModify.txt b/source/reference/command/findAndModify.txt index fa021dfea4f..4200ccab3e7 100644 --- a/source/reference/command/findAndModify.txt +++ b/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 `. +.. |let-option| replace:: :ref:`let ` + +.. include:: /includes/let-example-introduction.rst .. include:: /includes/let-example-find-modify-flavors.rst diff --git a/source/reference/command/update.txt b/source/reference/command/update.txt index 439013a736e..c4192318f85 100644 --- a/source/reference/command/update.txt +++ b/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 ` option or the :ref:`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 diff --git a/source/reference/method/db.collection.aggregate.txt b/source/reference/method/db.collection.aggregate.txt index 7348859e5b9..fd5f2d11c28 100644 --- a/source/reference/method/db.collection.aggregate.txt +++ b/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 ` option. +.. |let-option| replace:: :ref:`let ` + +.. include:: /includes/let-variables-match-note.rst .. include:: /includes/let-variables-example.rst diff --git a/source/reference/method/db.collection.findAndModify.txt b/source/reference/method/db.collection.findAndModify.txt index b0d171036e1..29b4a6bcbbf 100644 --- a/source/reference/method/db.collection.findAndModify.txt +++ b/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 `. +.. |let-option| replace:: :ref:`let ` + +.. include:: /includes/let-example-introduction.rst .. include:: /includes/let-example-find-modify-flavors.rst diff --git a/source/reference/method/db.collection.remove.txt b/source/reference/method/db.collection.remove.txt index 146e6b26cbc..c0cbdf7eca3 100644 --- a/source/reference/method/db.collection.remove.txt +++ b/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 `. +.. |let-option| replace:: :ref:`let ` + +.. include:: /includes/let-example-introduction.rst .. include:: /includes/let-example-delete-flavors.rst diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index 2b27fb7dcff..9d6cfd65fd7 100644 --- a/source/reference/method/db.collection.update.txt +++ b/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 `. +.. |let-option| replace:: :ref:`let ` + +.. include:: /includes/let-example-introduction.rst .. include:: /includes/let-example-update-flavors.rst