From d084f421564ba328593a7de725a05907159bb7db Mon Sep 17 00:00:00 2001 From: Andrew Feierabend Date: Tue, 29 Dec 2020 15:01:30 -0500 Subject: [PATCH] DOCSP-13696 correct sort stability language --- source/includes/fact-sort-consistency.rst | 7 ++++ source/includes/fact-sort-stability.rst | 11 ------- source/reference/command/findAndModify.txt | 6 ++-- source/reference/method/cursor.limit.txt | 20 +++++++----- source/reference/method/cursor.skip.txt | 22 +++++++------ source/reference/method/cursor.sort.txt | 19 ++++++----- .../method/db.collection.findAndModify.txt | 6 ++-- .../reference/operator/aggregation/limit.txt | 32 +++++++++++-------- .../reference/operator/aggregation/skip.txt | 32 +++++++++++-------- .../reference/operator/aggregation/sort.txt | 14 ++++---- source/release-notes/4.4-compatibility.txt | 8 ++--- source/release-notes/4.4.txt | 8 ++--- 12 files changed, 98 insertions(+), 87 deletions(-) create mode 100644 source/includes/fact-sort-consistency.rst delete mode 100644 source/includes/fact-sort-stability.rst diff --git a/source/includes/fact-sort-consistency.rst b/source/includes/fact-sort-consistency.rst new file mode 100644 index 00000000000..b884f9ca12a --- /dev/null +++ b/source/includes/fact-sort-consistency.rst @@ -0,0 +1,7 @@ +MongoDB does not store documents in a collection in a particular order. +When sorting on a field which contains duplicate values, documents +containing those values may be returned in any order. + +If consistent sort order is desired, include at least one field in your +sort that contains unique values. The easiest way to guarantee this is +to include the ``_id`` field in your sort query. diff --git a/source/includes/fact-sort-stability.rst b/source/includes/fact-sort-stability.rst deleted file mode 100644 index 67d5a9742da..00000000000 --- a/source/includes/fact-sort-stability.rst +++ /dev/null @@ -1,11 +0,0 @@ -In MongoDB, sorts are inherently stable, unless sorting on a field which -contains duplicate values: - -- a *stable sort* is one that returns the same sort order each time it - is performed -- an *unstable sort* is one that may return a different sort order - when performed multiple times - -If a stable sort is desired, include at least one field in your sort -that contains exclusively unique values. The easiest way to guarantee -this is to include the ``_id`` field in your sort query. diff --git a/source/reference/command/findAndModify.txt b/source/reference/command/findAndModify.txt index f1d2f6424c4..4bf8640c280 100644 --- a/source/reference/command/findAndModify.txt +++ b/source/reference/command/findAndModify.txt @@ -81,7 +81,7 @@ Definition - * - .. _findandmodify-command-stable-sorting: + * - .. _findandmodify-command-consistent-sorting: ``sort`` @@ -94,9 +94,9 @@ Definition Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the sort argument is not a document. - .. include:: /includes/fact-sort-stability.rst + .. include:: /includes/fact-sort-consistency.rst - See :ref:`sort-cursor-stable-sorting` for more information. + See :ref:`sort-cursor-consistent-sorting` for more information. diff --git a/source/reference/method/cursor.limit.txt b/source/reference/method/cursor.limit.txt index 643d9040d8c..e5a6edf31ff 100644 --- a/source/reference/method/cursor.limit.txt +++ b/source/reference/method/cursor.limit.txt @@ -69,11 +69,15 @@ Using ``limit()`` with ``sort()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If using :method:`~cursor.limit()` with :method:`~cursor.sort()`, be -sure that you are performing a *stable sort* before passing -results to :method:`~cursor.limit()`. A stable sort ensures that the -sort order of returned documents remains the same across multiple -executions of the same sort; especially important when used with the -:method:`~cursor.limit()` method. - -See :ref:`Stable sorting with the sort() method -` for more information. +sure to include at least one field in your sort that contains +unique values, before passing results to :method:`~cursor.limit()`. + +Sorting on fields that contain duplicate values may return an +inconsistent sort order for those duplicate fields over multiple +executions, especially when the collection is actively receiving writes. + +The easiest way to guarantee sort consistency is to include the +``_id`` field in your sort query. + +See :ref:`Consistent sorting with the sort() method +` for more information. diff --git a/source/reference/method/cursor.skip.txt b/source/reference/method/cursor.skip.txt index 66d0540ce15..62baf24db65 100644 --- a/source/reference/method/cursor.skip.txt +++ b/source/reference/method/cursor.skip.txt @@ -53,15 +53,19 @@ Behavior Using ``skip()`` with ``sort()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If using :method:`~cursor.skip()` with :method:`~cursor.sort()`, -be sure that you are performing a *stable sort* before passing -results to :method:`~cursor.skip()`. A stable sort ensures that the sort -order of returned documents remains the same across multiple executions -of the same sort; especially important when used with the -:method:`~cursor.skip()` method. - -See :ref:`Stable sorting with the sort() method -` for more information. +If using :method:`~cursor.skip()` with :method:`~cursor.sort()`, be +sure to include at least one field in your sort that contains +unique values, before passing results to :method:`~cursor.skip()`. + +Sorting on fields that contain duplicate values may return an +inconsistent sort order for those duplicate fields over multiple +executions, especially when the collection is actively receiving writes. + +The easiest way to guarantee sort consistency is to include the +``_id`` field in your sort query. + +See :ref:`Consistent sorting with the sort() method +` for more information. Pagination Example ------------------ diff --git a/source/reference/method/cursor.sort.txt b/source/reference/method/cursor.sort.txt index 175ffb5c138..5c4eb2c0c3c 100644 --- a/source/reference/method/cursor.sort.txt +++ b/source/reference/method/cursor.sort.txt @@ -60,14 +60,14 @@ Definition Behaviors --------- -.. _sort-cursor-stable-sorting: +.. _sort-cursor-consistent-sorting: -Sort Stability -~~~~~~~~~~~~~~ +Sort Consistency +~~~~~~~~~~~~~~~~ .. versionchanged:: 4.4 -.. include:: /includes/fact-sort-stability.rst +.. include:: /includes/fact-sort-consistency.rst Consider the following ``restaurant`` collection: @@ -88,13 +88,12 @@ on the ``borough`` field: db.restaurants.find().sort( { "borough": 1 } ) -In this example, the sort is *unstable*, since the ``borough`` field -contains duplicate values for both ``Manhattan`` and ``Brooklyn``. +In this example, sort order may be inconsistent, since the ``borough`` +field contains duplicate values for both ``Manhattan`` and ``Brooklyn``. Documents are returned in alphabetical order by ``borough``, but the order of those documents with duplicate values for ``borough`` might not -the be the same across multiple executions of the same sort. For -example, here are the results from two different executions of the -above command: +be the same across multiple executions of the same sort. For example, +here are the results from two different executions of the above command: .. code-block:: js :copyable: false @@ -115,7 +114,7 @@ While the values for ``borough`` are still sorted in alphabetical order, the order of the documents containing duplicate values for ``borough`` (i.e. ``Manhattan`` and ``Brooklyn``) is not the same. -To achieve a *stable sort*, add a field which contains exclusively +To achieve a *consistent sort*, add a field which contains exclusively unique values to the sort. The following command uses the :method:`~cursor.sort()` method to sort on both the ``borough`` field and the ``_id`` field: diff --git a/source/reference/method/db.collection.findAndModify.txt b/source/reference/method/db.collection.findAndModify.txt index c9e3100cfa5..e664848ed4c 100644 --- a/source/reference/method/db.collection.findAndModify.txt +++ b/source/reference/method/db.collection.findAndModify.txt @@ -89,7 +89,7 @@ Definition - * - .. _findandmodify-method-stable-sorting: + * - .. _findandmodify-method-consistent-sorting: ``sort`` @@ -102,9 +102,9 @@ Definition Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the sort argument is not a document. - .. include:: /includes/fact-sort-stability.rst + .. include:: /includes/fact-sort-consistency.rst - See :ref:`sort-cursor-stable-sorting` for more information. + See :ref:`sort-cursor-consistent-sorting` for more information. diff --git a/source/reference/operator/aggregation/limit.txt b/source/reference/operator/aggregation/limit.txt index af90d3ceb83..117a6dd659c 100644 --- a/source/reference/operator/aggregation/limit.txt +++ b/source/reference/operator/aggregation/limit.txt @@ -38,24 +38,28 @@ If using the :pipeline:`$limit` stage with any of: - the :pipeline:`$sort` aggregation stage, - the :method:`~cursor.sort()` method, or - the ``sort`` field to the :dbcommand:`findAndModify` command or the - :method:`~db.collection.findAndModify()` shell method. + :method:`~db.collection.findAndModify()` shell method, -be sure that you are performing a *stable sort* before passing results -to the :pipeline:`$limit` stage. A stable sort ensures that the sort -order of returned documents remains the same across multiple executions -of the same sort; especially important when used with the -:pipeline:`$limit` stage. +be sure to include at least one field in your sort that contains +unique values, before passing results to the :pipeline:`$limit` stage. + +Sorting on fields that contain duplicate values may return an +inconsistent sort order for those duplicate fields over multiple +executions, especially when the collection is actively receiving writes. + +The easiest way to guarantee sort consistency is to include the +``_id`` field in your sort query. See the following for more information on each: -- :ref:`Stable sorting with $sort (aggregation) - ` -- :ref:`Stable sorting with the sort() method - ` -- :ref:`Stable sorting with the findAndModify command - ` -- :ref:`Stable sorting with the findAndModify() method - ` +- :ref:`Consistent sorting with $sort (aggregation) + ` +- :ref:`Consistent sorting with the sort() shell method + ` +- :ref:`Consistent sorting with the findAndModify command + ` +- :ref:`Consistent sorting with the findAndModify() shell method + ` Example ------- diff --git a/source/reference/operator/aggregation/skip.txt b/source/reference/operator/aggregation/skip.txt index 1edc97b9a33..9975ae69594 100644 --- a/source/reference/operator/aggregation/skip.txt +++ b/source/reference/operator/aggregation/skip.txt @@ -39,24 +39,28 @@ If using the :pipeline:`$skip` stage with any of: - the :pipeline:`$sort` aggregation stage, - the :method:`~cursor.sort()` method, or - the ``sort`` field to the :dbcommand:`findAndModify` command or the - :method:`~db.collection.findAndModify()` shell method. + :method:`~db.collection.findAndModify()` shell method, -be sure that you are performing a *stable sort* before passing results -to the :pipeline:`$skip` stage. A stable sort ensures that the sort -order of returned documents remains the same across multiple executions -of the same sort; especially important when used with the -:pipeline:`$skip` stage. +be sure to include at least one field in your sort that contains +unique values, before passing results to the :pipeline:`$skip` stage. + +Sorting on fields that contain duplicate values may return a different +sort order for those duplicate fields over multiple executions, +especially when the collection is actively receiving writes. + +The easiest way to guarantee sort consistency is to include the +``_id`` field in your sort query. See the following for more information on each: -- :ref:`Stable sorting with $sort (aggregation) - ` -- :ref:`Stable sorting with the sort() method - ` -- :ref:`Stable sorting with the findAndModify command - ` -- :ref:`Stable sorting with the findAndModify() method - ` +- :ref:`Consistent sorting with $sort (aggregation) + ` +- :ref:`Consistent sorting with the sort() shell method + ` +- :ref:`Consistent sorting with the findAndModify command + ` +- :ref:`Consistent sorting with the findAndModify() shell method + ` Example ------- diff --git a/source/reference/operator/aggregation/sort.txt b/source/reference/operator/aggregation/sort.txt index d0bc5567935..21905be5778 100644 --- a/source/reference/operator/aggregation/sort.txt +++ b/source/reference/operator/aggregation/sort.txt @@ -55,12 +55,12 @@ Definition Behavior -------- -.. _sort-aggregation-stable-sorting: +.. _sort-aggregation-consistent-sorting: -Sort Stability -~~~~~~~~~~~~~~ +Sort Consistency +~~~~~~~~~~~~~~~~ -.. include:: /includes/fact-sort-stability.rst +.. include:: /includes/fact-sort-consistency.rst Consider the following ``restaurant`` collection: @@ -85,8 +85,8 @@ the ``borough`` field: ] ) -In this example, the sort is *unstable*, since the ``borough`` field -contains duplicate values for both ``Manhattan`` and ``Brooklyn``. +In this example, sort order may be inconsistent, since the ``borough`` +field contains duplicate values for both ``Manhattan`` and ``Brooklyn``. Documents are returned in alphabetical order by ``borough``, but the order of those documents with duplicate values for ``borough`` might not 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, the order of the documents containing duplicate values for ``borough`` (i.e. ``Manhattan`` and ``Brooklyn``) is not the same. -To achieve a *stable sort*, add a field which contains exclusively +To achieve a *consistent sort*, add a field which contains exclusively unique values to the sort. The following command uses the :pipeline:`$sort` stage to sort on both the ``borough`` field and the ``_id`` field: diff --git a/source/release-notes/4.4-compatibility.txt b/source/release-notes/4.4-compatibility.txt index 2dc58418d54..e1e193d2155 100644 --- a/source/release-notes/4.4-compatibility.txt +++ b/source/release-notes/4.4-compatibility.txt @@ -182,8 +182,8 @@ Text Search Metadata { $meta: "textScore" } Query Requirement .. include:: /includes/extracts/4.4-changes-textscore-predicate.rst -``$sort`` Stability Changes ---------------------------- +``$sort`` Changes +----------------- Starting in MongoDB 4.4, the :method:`~cursor.sort()` method now uses the same sort algorithm as the :pipeline:`$sort` aggregation stage. With @@ -191,14 +191,14 @@ this change, queries which perform a :method:`~cursor.sort()` on fields that contain duplicate values are much more likely to result in inconsistent sort orders for those values. -To guarantee sort stability when using :method:`~cursor.sort()` on +To guarantee sort consistency when using :method:`~cursor.sort()` on duplicate values, include an additional field in your sort that contains exclusively unique values. This can be accomplished easily by adding the ``_id`` field to your sort. -See :ref:`sort-cursor-stable-sorting` for more information. +See :ref:`sort-cursor-consistent-sorting` for more information. Map Reduce Changes ------------------ diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index 8a77a2c67e9..eab82032dda 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -1020,8 +1020,8 @@ Transactions Sorting ------- -``$sort`` Stability Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``$sort`` Changes +~~~~~~~~~~~~~~~~~ Starting in MongoDB 4.4, the :method:`~cursor.sort()` method now uses the same sort algorithm as the :pipeline:`$sort` aggregation stage. With @@ -1029,14 +1029,14 @@ this change, queries which perform a :method:`~cursor.sort()` on fields that contain duplicate values are much more likely to result in inconsistent sort orders for those values. -To guarantee sort stability when using :method:`~cursor.sort()` on +To guarantee sort consistency when using :method:`~cursor.sort()` on duplicate values, include an additional field in your sort that contains exclusively unique values. This can be accomplished easily by adding the ``_id`` field to your sort. -See :ref:`sort-cursor-stable-sorting` for more information. +See :ref:`sort-cursor-consistent-sorting` for more information. Security Improvements ---------------------