Skip to content

DOCS-4062: Natural order clarification #2023

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 6 additions & 12 deletions source/reference/glossary.txt
Original file line number Diff line number Diff line change
Expand Up @@ -498,18 +498,12 @@ Glossary
belong to a namespace. See :ref:`faq-dev-namespace`.

natural order
The order that a database stores documents on disk. Typically,
the order of documents on disks reflects insertion order, except
when a document moves internally because an update operation
increases its size. In :term:`capped collections <capped
collection>`, insertion order and natural order are identical
because documents do not move internally. MongoDB returns
documents in forward natural order for a
:method:`~db.collection.find()` query with no parameters.
MongoDB returns documents in reverse natural order for a
:method:`~db.collection.find()` query :method:`sorted
<cursor.sort()>` with a parameter of ``$natural:-1``. See
:operator:`$natural`.
The order in which the database refers to documents on disk. This is the
default sort order. See :operator:`$natural` and
:ref:`return-natural-order`.

storage order
See :term:`natural order`.

ObjectId
A special 12-byte :term:`BSON` type that guarantees uniqueness
Expand Down
15 changes: 9 additions & 6 deletions source/reference/method/cursor.sort.txt
Original file line number Diff line number Diff line change
Expand Up @@ -189,14 +189,17 @@ The query returns the following documents, ordered first by the
{ "_id" : 3, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 15 }

.. _return-storage-order:
.. _return-natural-order:

Return in Storage Order
Return in Natural Order
-----------------------

The :operator:`$natural` parameter returns items according to their
storage order within the collection level extents.
:term:`natural order` within the database. This ordering is an internal
implementation feature, and you should not rely on any particular structure
within it.

Typically, the storage order reflects insertion order, *except* when
Typically, the natural order reflects insertion order, *except* when
documents relocate because of :ref:`document growth due to updates
<data-model-document-growth>` or remove operations free up space which
are then taken up by newly inserted documents.
Expand All @@ -212,7 +215,7 @@ Consider the sequence of insert operations to the ``trees`` collection:
db.trees.insert( { _id: 3, common_name: "maple", genus: "aceraceae" } )
db.trees.insert( { _id: 4, common_name: "birch", genus: "betula" } )

The following query returns the documents in the storage order:
The following query returns the documents in the natural order:

.. code-block:: javascript

Expand All @@ -236,13 +239,13 @@ Update a document such that the document outgrows its current allotted space:
{ $set: { famous_oaks: [ "Emancipation Oak", "Goethe Oak" ] } }
)

Rerun the query to returns the documents in the storage order:
Rerun the query to returns the documents in natural order:

.. code-block:: javascript

db.trees.find().sort( { $natural: 1 } )

The documents return in the following storage order:
The documents return in the following natural order:

.. code-block:: javascript

Expand Down
7 changes: 4 additions & 3 deletions source/reference/operator/meta/natural.txt
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,9 @@ Definition
.. operator:: $natural

Use the :operator:`$natural` operator to use :term:`natural order` for
the results of a sort operation. Natural order refers to the
:ref:`storage order <return-storage-order>` of documents in the file on disk.
the results of a sort operation. Natural order refers to the logical
:ref:`ordering <return-natural-order>` of documents internally within the
database.

The :operator:`$natural` operator uses the following syntax to return
documents in the order they exist on disk:
Expand All @@ -24,7 +25,7 @@ Behavior
--------

On a sharded collection the :operator:`$natural` operator returns a
collection scan sorted in :ref:`storage order<return-storage-order>`, the
collection scan sorted in :ref:`natural order<return-natural-order>`, the
order the database inserts and stores documents on disk.

.. include:: /includes/fact-natural-parameter.rst
Expand Down