mongodb · jmd-mongo · Sep 1, 2021
diff --git a/source/includes/fact-update-operator-lexicographic-order.rst b/source/includes/fact-update-operator-lexicographic-order.rst
@@ -0,0 +1,3 @@
+In MongoDB 4.4 and earlier, update operators process document fields 
+in lexicographic order. See :ref:`Update Operators Behavior 
+<update-operators-lexicographic-order>` for details.
diff --git a/source/reference/operator/update.txt b/source/reference/operator/update.txt
@@ -31,6 +31,30 @@ Specify the operator expression in a document of the form:
 Update Operators
 ----------------
 
+.. _update-operators-lexicographic-order:
+
+Behavior
+~~~~~~~~
+
+In MongoDB 4.4 and earlier, update operators process all document fields 
+in lexicographic order. 
+
+In MongoDB 5.0 and later, update operators process document fields with
+string-based names in lexicographic order. Fields with numeric names are
+processed in numeric order. 
+
+Consider this example :update:`$set` command:
+
+.. code-block:: javascript
+
+  { $set: { "a.2": <new value>, "a.10": <new value>, } }
+
+In MongoDB 4.4, ``"a.10"`` is processed before ``"a.2"`` because ``10`` 
+comes before ``2`` in lexicographic order. 
+
+In MongoDB 5.0, ``"a.2"`` is processed before ``"a.10"`` because ``2``
+comes before ``10`` in numeric order. 
+
 Fields
 ~~~~~~
 

diff --git 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-lexicographic-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
@@ -37,6 +37,11 @@ Definition
       constructor to specify integers. See :ref:`shell-type-int` or
       :ref:`shell-type-long` for more information.
 
+Behavior
+--------
+
+.. include:: /includes/fact-update-operator-lexicographic-order.rst
+
 Examples
 --------
 

diff --git a/source/reference/operator/update/currentDate.txt b/source/reference/operator/update/currentDate.txt
@@ -49,6 +49,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-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
@@ -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-lexicographic-order.rst
+
 Examples
 --------
 

diff --git a/source/reference/operator/update/inc.txt b/source/reference/operator/update/inc.txt
@@ -23,10 +23,12 @@ Definition
       { $inc: { <field1>: <amount1>, <field2>: <amount2>, ... } }
 
    .. include:: /includes/use-dot-notation.rst
-
+      
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-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
@@ -32,6 +32,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-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
@@ -30,7 +30,9 @@ Definition
 Behavior
 --------
 
-If the field does not exists, the :update:`$min` operator sets the
+.. include:: /includes/fact-update-operator-lexicographic-order.rst
+
+If the field does not exist, the :update:`$min` operator sets the
 field to the specified value.
 
 For comparisons between values of different types, such as a number and

diff --git a/source/reference/operator/update/mul.txt b/source/reference/operator/update/mul.txt
@@ -31,6 +31,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-order.rst
+
 Missing Field
 ~~~~~~~~~~~~~
 

diff --git 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-lexicographic-order.rst
+
 The :update:`$pop` operation fails if the ``<field>`` 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
@@ -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-lexicographic-order.rst
 
 Examples
 --------

diff --git 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-lexicographic-order.rst
+
 ``upsert``
 ~~~~~~~~~~~
 

diff --git 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-lexicographic-order.rst
+
 ``upsert``
 ~~~~~~~~~~~
 

diff --git 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-lexicographic-order.rst
+
 ``upsert``
 ~~~~~~~~~~~
 

diff --git 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-lexicographic-order.rst
+
 If you specify a ``<condition>`` and the array elements are embedded
 documents, :update:`$pull` operator applies the ``<condition>`` 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
@@ -31,6 +31,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-order.rst
+
 If a ``<value>`` to remove is a document or an array,
 :update:`$pullAll` removes only the elements in the array that match
 the specified ``<value>`` exactly, including order.

diff --git 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-lexicographic-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
@@ -37,6 +37,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-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
@@ -29,6 +29,8 @@ Definition
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-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
@@ -35,6 +35,11 @@ Definition
 
    .. include:: /includes/use-dot-notation.rst
 
+Behavior
+--------
+
+.. include:: /includes/fact-update-operator-lexicographic-order.rst
+
 Example
 --------
 

diff --git a/source/reference/operator/update/slice.txt b/source/reference/operator/update/slice.txt
@@ -60,6 +60,8 @@ $slice
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-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
@@ -47,6 +47,8 @@ $sort
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-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
@@ -27,6 +27,8 @@ $unset
 Behavior
 --------
 
+.. include:: /includes/fact-update-operator-lexicographic-order.rst
+
 If the field does not exist, then :update:`$unset` does nothing (i.e.
 no operation).
-Original file line number
+Diff line change
@@ Expand Up / @@ -35,6 +35,11 @@ Definition @@
        .. include:: /includes/use-dot-notation.rst
+    Behavior
+    --------
+    .. include:: /includes/fact-update-operator-lexicographic-order.rst
     Example
     --------
@@ Expand Down @@