diff --git a/source/includes/fact-update-operator-processing-order.rst b/source/includes/fact-update-operator-processing-order.rst new file mode 100644 index 00000000000..3eddf446867 --- /dev/null +++ b/source/includes/fact-update-operator-processing-order.rst @@ -0,0 +1,4 @@ +Starting in MongoDB 5.0, update operators process document fields with +string-based names in lexicographic order. Fields with numeric names are +processed in numeric order. See :ref:`Update Operators Behavior +` for details. diff --git a/source/reference/operator/update.txt b/source/reference/operator/update.txt index 171d7486ee0..4a00499e340 100644 --- a/source/reference/operator/update.txt +++ b/source/reference/operator/update.txt @@ -33,6 +33,30 @@ Specify the operator expression in a document of the form: Update Operators ---------------- +.. _update-operators-processing-order: + +Behavior +~~~~~~~~ + +Starting in MongoDB 5.0, update operators process document fields with +string-based names in lexicographic order. Fields with numeric names are +processed in numeric order. + +In MongoDB 4.4 and earlier, update operators process all document fields +in lexicographic order. + +Consider this example :update:`$set` command: + +.. code-block:: javascript + + { $set: { "a.2": , "a.10": , } } + +In MongoDB 5.0 and later, ``"a.2"`` is processed before ``"a.10"`` +because ``2`` comes before ``10`` in numeric order. + +In MongoDB 4.4 and earlier, ``"a.10"`` is processed before ``"a.2"`` +because ``10`` comes before ``2`` in lexicographic order. + Fields ~~~~~~ diff --git a/source/reference/operator/update/addToSet.txt b/source/reference/operator/update/addToSet.txt index 3a8baba5164..6e9ef5b4c09 100644 --- a/source/reference/operator/update/addToSet.txt +++ b/source/reference/operator/update/addToSet.txt @@ -30,6 +30,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + :update:`$addToSet` only ensures that there are no duplicate items *added* to the set and does not affect existing duplicate elements. :update:`$addToSet` does not guarantee a particular ordering of diff --git a/source/reference/operator/update/bit.txt b/source/reference/operator/update/bit.txt index 2190dd452bb..fc423f0f50d 100644 --- a/source/reference/operator/update/bit.txt +++ b/source/reference/operator/update/bit.txt @@ -42,6 +42,8 @@ Behavior .. include:: /includes/extracts/update-operation-empty-operand-expressions-bit.rst +.. include:: /includes/fact-update-operator-processing-order.rst + Examples -------- diff --git a/source/reference/operator/update/currentDate.txt b/source/reference/operator/update/currentDate.txt index 8666b386598..105e09a4898 100644 --- a/source/reference/operator/update/currentDate.txt +++ b/source/reference/operator/update/currentDate.txt @@ -41,6 +41,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exist, :update:`$currentDate` adds the field to a document. diff --git a/source/reference/operator/update/each.txt b/source/reference/operator/update/each.txt index f7e9c2a19dc..d66a5a21ca0 100644 --- a/source/reference/operator/update/each.txt +++ b/source/reference/operator/update/each.txt @@ -37,6 +37,11 @@ Definition other modifiers. For a list of modifiers available for :update:`$push`, see :ref:`push-modifiers`. +Behavior +-------- + +.. include:: /includes/fact-update-operator-processing-order.rst + Examples -------- diff --git a/source/reference/operator/update/inc.txt b/source/reference/operator/update/inc.txt index 0c50298008e..e5d2828ce0e 100644 --- a/source/reference/operator/update/inc.txt +++ b/source/reference/operator/update/inc.txt @@ -23,10 +23,12 @@ Definition { $inc: { : , : , ... } } .. include:: /includes/use-dot-notation.rst - + Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The :update:`$inc` operator accepts positive and negative values. If the field does not exist, :update:`$inc` creates the field and sets diff --git a/source/reference/operator/update/max.txt b/source/reference/operator/update/max.txt index ce79fc44727..06e9ba5a80e 100644 --- a/source/reference/operator/update/max.txt +++ b/source/reference/operator/update/max.txt @@ -32,6 +32,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exists, the :update:`$max` operator sets the field to the specified value. diff --git a/source/reference/operator/update/min.txt b/source/reference/operator/update/min.txt index 03eb39233cd..7f2031ba407 100644 --- a/source/reference/operator/update/min.txt +++ b/source/reference/operator/update/min.txt @@ -30,6 +30,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exist, the :update:`$min` operator sets the field to the specified value. diff --git a/source/reference/operator/update/mul.txt b/source/reference/operator/update/mul.txt index 0ac2e62bc27..1ed6bc17aeb 100644 --- a/source/reference/operator/update/mul.txt +++ b/source/reference/operator/update/mul.txt @@ -31,6 +31,8 @@ Behavior .. include:: /includes/extracts/update-operation-empty-operand-expressions-mul.rst +.. include:: /includes/fact-update-operator-processing-order.rst + Missing Field ~~~~~~~~~~~~~ diff --git a/source/reference/operator/update/pop.txt b/source/reference/operator/update/pop.txt index 8b568b119c8..2fcd206c167 100644 --- a/source/reference/operator/update/pop.txt +++ b/source/reference/operator/update/pop.txt @@ -31,6 +31,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The :update:`$pop` operation fails if the ```` is not an array. If the :update:`$pop` operator removes the last item in the diff --git a/source/reference/operator/update/position.txt b/source/reference/operator/update/position.txt index 244cf1a0a8a..2a0d60e9c3a 100644 --- a/source/reference/operator/update/position.txt +++ b/source/reference/operator/update/position.txt @@ -58,6 +58,10 @@ Definition greater than or equal to the length of the array, the :update:`$push` adds elements to the beginning of the array. +Behavior +-------- + +.. include:: /includes/fact-update-operator-processing-order.rst Examples -------- diff --git a/source/reference/operator/update/positional-all.txt b/source/reference/operator/update/positional-all.txt index d27813e3489..a960d837ca1 100644 --- a/source/reference/operator/update/positional-all.txt +++ b/source/reference/operator/update/positional-all.txt @@ -43,6 +43,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + ``upsert`` ~~~~~~~~~~~ diff --git a/source/reference/operator/update/positional-filtered.txt b/source/reference/operator/update/positional-filtered.txt index d76f4c3440f..3e1fe6bada2 100644 --- a/source/reference/operator/update/positional-filtered.txt +++ b/source/reference/operator/update/positional-filtered.txt @@ -52,6 +52,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + ``upsert`` ~~~~~~~~~~~ diff --git a/source/reference/operator/update/positional.txt b/source/reference/operator/update/positional.txt index 53bd2d557b3..aece7dd1a3e 100644 --- a/source/reference/operator/update/positional.txt +++ b/source/reference/operator/update/positional.txt @@ -59,6 +59,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + ``upsert`` ~~~~~~~~~~~ diff --git a/source/reference/operator/update/pull.txt b/source/reference/operator/update/pull.txt index e3cf66f62be..1afb922beae 100644 --- a/source/reference/operator/update/pull.txt +++ b/source/reference/operator/update/pull.txt @@ -26,6 +26,8 @@ $pull Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If you specify a ```` and the array elements are embedded documents, :update:`$pull` operator applies the ```` as if each array element were a document in a collection. See diff --git a/source/reference/operator/update/pullAll.txt b/source/reference/operator/update/pullAll.txt index f0c1f2478e0..534ff0aad11 100644 --- a/source/reference/operator/update/pullAll.txt +++ b/source/reference/operator/update/pullAll.txt @@ -31,6 +31,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If a ```` to remove is a document or an array, :update:`$pullAll` removes only the elements in the array that match the specified ```` exactly, including order. diff --git a/source/reference/operator/update/push.txt b/source/reference/operator/update/push.txt index a7440b74756..7e0aebf383c 100644 --- a/source/reference/operator/update/push.txt +++ b/source/reference/operator/update/push.txt @@ -28,6 +28,8 @@ Definition Behavior --------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field is absent in the document to update, :update:`$push` adds the array field with the value as its element. diff --git a/source/reference/operator/update/rename.txt b/source/reference/operator/update/rename.txt index 587aadaa037..faa50b551c7 100644 --- a/source/reference/operator/update/rename.txt +++ b/source/reference/operator/update/rename.txt @@ -37,6 +37,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The :update:`$rename` operator logically performs an :update:`$unset` of both the old name and the new name, and then performs a :update:`$set` operation with the new name. As such, the operation may diff --git a/source/reference/operator/update/set.txt b/source/reference/operator/update/set.txt index 2c1e926b7c1..c2a6afea055 100644 --- a/source/reference/operator/update/set.txt +++ b/source/reference/operator/update/set.txt @@ -32,11 +32,11 @@ Definition .. include:: /includes/use-dot-notation.rst - - Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exist, :update:`$set` will add a new field with the specified value, provided that the new field does not violate a type constraint. diff --git a/source/reference/operator/update/setOnInsert.txt b/source/reference/operator/update/setOnInsert.txt index 221468c509b..da4ffb364a9 100644 --- a/source/reference/operator/update/setOnInsert.txt +++ b/source/reference/operator/update/setOnInsert.txt @@ -38,6 +38,11 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + +Example +-------- + .. include:: /includes/extracts/update-operation-empty-operand-expressions-set-on-insert.rst Example diff --git a/source/reference/operator/update/slice.txt b/source/reference/operator/update/slice.txt index 820bb606513..133cae4491d 100644 --- a/source/reference/operator/update/slice.txt +++ b/source/reference/operator/update/slice.txt @@ -58,6 +58,8 @@ $slice Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The order in which the modifiers appear is immaterial. Previous versions required the :update:`$each` modifier to appear as the first modifier if used in conjunction with :update:`$slice`. For a list of diff --git a/source/reference/operator/update/sort.txt b/source/reference/operator/update/sort.txt index 2b61c1b4eea..e0d3a0b7279 100644 --- a/source/reference/operator/update/sort.txt +++ b/source/reference/operator/update/sort.txt @@ -47,6 +47,8 @@ $sort Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + The :update:`$sort` modifier can sort array elements that are not documents. In previous versions, the :update:`$sort` modifier required the array elements be documents. diff --git a/source/reference/operator/update/unset.txt b/source/reference/operator/update/unset.txt index c3a123760bf..f4ea7a060bc 100644 --- a/source/reference/operator/update/unset.txt +++ b/source/reference/operator/update/unset.txt @@ -36,6 +36,8 @@ Definition Behavior -------- +.. include:: /includes/fact-update-operator-processing-order.rst + If the field does not exist, then :update:`$unset` does nothing (i.e. no operation). diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 974cc155ca1..a2144e5426c 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -232,6 +232,11 @@ operand expression ( ``{ }`` ): An empty update results in no changes and no :term:`oplog` entry is created (meaning that the operation is a no-op). +Update Operator Processing Order +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-update-operator-processing-order.rst + Aggregation Pipeline Operator Parameter Limits ----------------------------------------------