Skip to content

Commit 905589f

Browse files
committed
DOCSP-13696 correct sort stability language
1 parent f0d1b2c commit 905589f

File tree

12 files changed

+98
-87
lines changed

12 files changed

+98
-87
lines changed
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
MongoDB does not store documents in a collection in a particular order.
2+
When sorting on a field which contains duplicate values, documents
3+
containing those values may be returned in any order.
4+
5+
If consistent sort order is desired, include at least one field in your
6+
sort that contains unique values. The easiest way to guarantee this is
7+
to include the ``_id`` field in your sort query.

source/includes/fact-sort-stability.rst

Lines changed: 0 additions & 11 deletions
This file was deleted.

source/reference/command/findAndModify.txt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ Definition
8181

8282

8383

84-
* - .. _findandmodify-command-stable-sorting:
84+
* - .. _findandmodify-command-consistent-sorting:
8585

8686
``sort``
8787

@@ -94,9 +94,9 @@ Definition
9494
Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation
9595
errors if the sort argument is not a document.
9696

97-
.. include:: /includes/fact-sort-stability.rst
97+
.. include:: /includes/fact-sort-consistency.rst
9898

99-
See :ref:`sort-cursor-stable-sorting` for more information.
99+
See :ref:`sort-cursor-consistent-sorting` for more information.
100100

101101

102102

source/reference/method/cursor.limit.txt

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -69,11 +69,15 @@ Using ``limit()`` with ``sort()``
6969
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7070

7171
If using :method:`~cursor.limit()` with :method:`~cursor.sort()`, be
72-
sure that you are performing a *stable sort* before passing
73-
results to :method:`~cursor.limit()`. A stable sort ensures that the
74-
sort order of returned documents remains the same across multiple
75-
executions of the same sort; especially important when used with the
76-
:method:`~cursor.limit()` method.
77-
78-
See :ref:`Stable sorting with the sort() method
79-
<sort-cursor-stable-sorting>` for more information.
72+
sure to include at least one field in your sort that contains
73+
unique values, before passing results to :method:`~cursor.limit()`.
74+
75+
Sorting on fields that contain duplicate values may return an
76+
inconsistent sort order for those duplicate fields over multiple
77+
executions, especially when the collection is actively receiving writes.
78+
79+
The easiest way to guarantee sort consistency is to include the
80+
``_id`` field in your sort query.
81+
82+
See :ref:`Consistent sorting with the sort() method
83+
<sort-cursor-consistent-sorting>` for more information.

source/reference/method/cursor.skip.txt

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -53,15 +53,19 @@ Behavior
5353
Using ``skip()`` with ``sort()``
5454
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5555

56-
If using :method:`~cursor.skip()` with :method:`~cursor.sort()`,
57-
be sure that you are performing a *stable sort* before passing
58-
results to :method:`~cursor.skip()`. A stable sort ensures that the sort
59-
order of returned documents remains the same across multiple executions
60-
of the same sort; especially important when used with the
61-
:method:`~cursor.skip()` method.
62-
63-
See :ref:`Stable sorting with the sort() method
64-
<sort-cursor-stable-sorting>` for more information.
56+
If using :method:`~cursor.skip()` with :method:`~cursor.sort()`, be
57+
sure to include at least one field in your sort that contains
58+
unique values, before passing results to :method:`~cursor.skip()`.
59+
60+
Sorting on fields that contain duplicate values may return an
61+
inconsistent sort order for those duplicate fields over multiple
62+
executions, especially when the collection is actively receiving writes.
63+
64+
The easiest way to guarantee sort consistency is to include the
65+
``_id`` field in your sort query.
66+
67+
See :ref:`Consistent sorting with the sort() method
68+
<sort-cursor-consistent-sorting>` for more information.
6569

6670
Pagination Example
6771
------------------

source/reference/method/cursor.sort.txt

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -60,14 +60,14 @@ Definition
6060
Behaviors
6161
---------
6262

63-
.. _sort-cursor-stable-sorting:
63+
.. _sort-cursor-consistent-sorting:
6464

65-
Sort Stability
66-
~~~~~~~~~~~~~~
65+
Sort Consistency
66+
~~~~~~~~~~~~~~~~
6767

6868
.. versionchanged:: 4.4
6969

70-
.. include:: /includes/fact-sort-stability.rst
70+
.. include:: /includes/fact-sort-consistency.rst
7171

7272
Consider the following ``restaurant`` collection:
7373

@@ -88,13 +88,12 @@ on the ``borough`` field:
8888

8989
db.restaurants.find().sort( { "borough": 1 } )
9090

91-
In this example, the sort is *unstable*, since the ``borough`` field
92-
contains duplicate values for both ``Manhattan`` and ``Brooklyn``.
91+
In this example, sort order may be inconsistent, since the ``borough``
92+
field contains duplicate values for both ``Manhattan`` and ``Brooklyn``.
9393
Documents are returned in alphabetical order by ``borough``, but the
9494
order of those documents with duplicate values for ``borough`` might not
95-
the be the same across multiple executions of the same sort. For
96-
example, here are the results from two different executions of the
97-
above command:
95+
be the same across multiple executions of the same sort. For example,
96+
here are the results from two different executions of the above command:
9897

9998
.. code-block:: js
10099
:copyable: false
@@ -115,7 +114,7 @@ While the values for ``borough`` are still sorted in alphabetical order,
115114
the order of the documents containing duplicate values for ``borough``
116115
(i.e. ``Manhattan`` and ``Brooklyn``) is not the same.
117116

118-
To achieve a *stable sort*, add a field which contains exclusively
117+
To achieve a *consistent sort*, add a field which contains exclusively
119118
unique values to the sort. The following command uses the
120119
:method:`~cursor.sort()` method to sort on both the ``borough`` field
121120
and the ``_id`` field:

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ Definition
8989

9090

9191

92-
* - .. _findandmodify-method-stable-sorting:
92+
* - .. _findandmodify-method-consistent-sorting:
9393

9494
``sort``
9595

@@ -102,9 +102,9 @@ Definition
102102
Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation
103103
errors if the sort argument is not a document.
104104

105-
.. include:: /includes/fact-sort-stability.rst
105+
.. include:: /includes/fact-sort-consistency.rst
106106

107-
See :ref:`sort-cursor-stable-sorting` for more information.
107+
See :ref:`sort-cursor-consistent-sorting` for more information.
108108

109109

110110

source/reference/operator/aggregation/limit.txt

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -38,24 +38,28 @@ If using the :pipeline:`$limit` stage with any of:
3838
- the :pipeline:`$sort` aggregation stage,
3939
- the :method:`~cursor.sort()` method, or
4040
- the ``sort`` field to the :dbcommand:`findAndModify` command or the
41-
:method:`~db.collection.findAndModify()` shell method.
41+
:method:`~db.collection.findAndModify()` shell method,
4242

43-
be sure that you are performing a *stable sort* before passing results
44-
to the :pipeline:`$limit` stage. A stable sort ensures that the sort
45-
order of returned documents remains the same across multiple executions
46-
of the same sort; especially important when used with the
47-
:pipeline:`$limit` stage.
43+
be sure to include at least one field in your sort that contains
44+
unique values, before passing results to the :pipeline:`$limit` stage.
45+
46+
Sorting on fields that contain duplicate values may return an
47+
inconsistent sort order for those duplicate fields over multiple
48+
executions, especially when the collection is actively receiving writes.
49+
50+
The easiest way to guarantee sort consistency is to include the
51+
``_id`` field in your sort query.
4852

4953
See the following for more information on each:
5054

51-
- :ref:`Stable sorting with $sort (aggregation)
52-
<sort-aggregation-stable-sorting>`
53-
- :ref:`Stable sorting with the sort() method
54-
<sort-cursor-stable-sorting>`
55-
- :ref:`Stable sorting with the findAndModify command
56-
<findandmodify-command-stable-sorting>`
57-
- :ref:`Stable sorting with the findAndModify() method
58-
<findandmodify-method-stable-sorting>`
55+
- :ref:`Consistent sorting with $sort (aggregation)
56+
<sort-aggregation-consistent-sorting>`
57+
- :ref:`Consistent sorting with the sort() shell method
58+
<sort-cursor-consistent-sorting>`
59+
- :ref:`Consistent sorting with the findAndModify command
60+
<findandmodify-command-consistent-sorting>`
61+
- :ref:`Consistent sorting with the findAndModify() shell method
62+
<findandmodify-method-consistent-sorting>`
5963

6064
Example
6165
-------

source/reference/operator/aggregation/skip.txt

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -39,24 +39,28 @@ If using the :pipeline:`$skip` stage with any of:
3939
- the :pipeline:`$sort` aggregation stage,
4040
- the :method:`~cursor.sort()` method, or
4141
- the ``sort`` field to the :dbcommand:`findAndModify` command or the
42-
:method:`~db.collection.findAndModify()` shell method.
42+
:method:`~db.collection.findAndModify()` shell method,
4343

44-
be sure that you are performing a *stable sort* before passing results
45-
to the :pipeline:`$skip` stage. A stable sort ensures that the sort
46-
order of returned documents remains the same across multiple executions
47-
of the same sort; especially important when used with the
48-
:pipeline:`$skip` stage.
44+
be sure to include at least one field in your sort that contains
45+
unique values, before passing results to the :pipeline:`$skip` stage.
46+
47+
Sorting on fields that contain duplicate values may return a different
48+
sort order for those duplicate fields over multiple executions,
49+
especially when the collection is actively receiving writes.
50+
51+
The easiest way to guarantee sort consistency is to include the
52+
``_id`` field in your sort query.
4953

5054
See the following for more information on each:
5155

52-
- :ref:`Stable sorting with $sort (aggregation)
53-
<sort-aggregation-stable-sorting>`
54-
- :ref:`Stable sorting with the sort() method
55-
<sort-cursor-stable-sorting>`
56-
- :ref:`Stable sorting with the findAndModify command
57-
<findandmodify-command-stable-sorting>`
58-
- :ref:`Stable sorting with the findAndModify() method
59-
<findandmodify-method-stable-sorting>`
56+
- :ref:`Consistent sorting with $sort (aggregation)
57+
<sort-aggregation-consistent-sorting>`
58+
- :ref:`Consistent sorting with the sort() shell method
59+
<sort-cursor-consistent-sorting>`
60+
- :ref:`Consistent sorting with the findAndModify command
61+
<findandmodify-command-consistent-sorting>`
62+
- :ref:`Consistent sorting with the findAndModify() shell method
63+
<findandmodify-method-consistent-sorting>`
6064

6165
Example
6266
-------

source/reference/operator/aggregation/sort.txt

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -55,12 +55,12 @@ Definition
5555
Behavior
5656
--------
5757

58-
.. _sort-aggregation-stable-sorting:
58+
.. _sort-aggregation-consistent-sorting:
5959

60-
Sort Stability
61-
~~~~~~~~~~~~~~
60+
Sort Consistency
61+
~~~~~~~~~~~~~~~~
6262

63-
.. include:: /includes/fact-sort-stability.rst
63+
.. include:: /includes/fact-sort-consistency.rst
6464

6565
Consider the following ``restaurant`` collection:
6666

@@ -85,8 +85,8 @@ the ``borough`` field:
8585
]
8686
)
8787

88-
In this example, the sort is *unstable*, since the ``borough`` field
89-
contains duplicate values for both ``Manhattan`` and ``Brooklyn``.
88+
In this example, sort order may be inconsistent, since the ``borough``
89+
field contains duplicate values for both ``Manhattan`` and ``Brooklyn``.
9090
Documents are returned in alphabetical order by ``borough``, but the
9191
order of those documents with duplicate values for ``borough`` might not
9292
the be the same across multiple executions of the same sort. For
@@ -112,7 +112,7 @@ While the values for ``borough`` are still sorted in alphabetical order,
112112
the order of the documents containing duplicate values for ``borough``
113113
(i.e. ``Manhattan`` and ``Brooklyn``) is not the same.
114114

115-
To achieve a *stable sort*, add a field which contains exclusively
115+
To achieve a *consistent sort*, add a field which contains exclusively
116116
unique values to the sort. The following command uses the
117117
:pipeline:`$sort` stage to sort on both the ``borough`` field and the
118118
``_id`` field:

0 commit comments

Comments
 (0)