diff --git a/source/includes/fact-natural-parameter.rst b/source/includes/fact-natural-parameter.rst new file mode 100644 index 00000000000..e69de29bb2d diff --git a/source/reference/method/cursor.sort.txt b/source/reference/method/cursor.sort.txt index 640ffb72868..1fe2cf95368 100644 --- a/source/reference/method/cursor.sort.txt +++ b/source/reference/method/cursor.sort.txt @@ -180,6 +180,8 @@ The query returns the following documents, ordered first by the { "_id" : 2, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 50 } { "_id" : 3, "item" : { "category" : "cookies", "type" : "chocolate chip" }, "amount" : 15 } +.. _return-storage-order: + Return in Storage Order ----------------------- @@ -191,6 +193,8 @@ documents relocate because of :ref:`document growth due to updates ` or remove operations free up space which are then taken up by newly inserted documents. +.. include:: /includes/fact-natural-parameter.rst + Consider the sequence of insert operations to the ``trees`` collection: .. code-block:: javascript diff --git a/source/reference/operator/meta/natural.txt b/source/reference/operator/meta/natural.txt index 85370d1d811..e393ca6c075 100644 --- a/source/reference/operator/meta/natural.txt +++ b/source/reference/operator/meta/natural.txt @@ -4,11 +4,14 @@ $natural .. default-domain:: mongodb +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 - order of documents in the file on disk. + :ref:`storage order ` of documents in the file on disk. The :operator:`$natural` operator uses the following syntax to return documents in the order they exist on disk: @@ -17,13 +20,116 @@ $natural db.collection.find().sort( { $natural: 1 } ) - Use ``-1`` to return documents in the reverse order as they occur on - disk: +Behavior +-------- + +On a sharded collection the :operator:`$natural` operator returns a +collection scan sorted in :ref:`storage order`, the +order the database inserts and stores documents on disk. + +.. include:: /includes/fact-natural-parameter.rst + +.. include:: /includes/fact-natural-sort-order-text-query-restriction.rst + +Examples +-------- + +Reverse Order +~~~~~~~~~~~~~ + +Use ``-1`` to return documents in the reverse order as they occur on disk: + +.. code-block:: javascript + + db.collection.find().sort( { $natural: -1 } ) + +Natural Order Comparison +~~~~~~~~~~~~~~~~~~~~~~~~ + +In this scenario: + +- Create an extra index as { normal: 1 }. + +- Insert relevant objects with ``_id`` and ``normal`` values, for example, + a string type object created with: .. code-block:: javascript - db.collection.find().sort( { $natural: -1 } ) + db.coll.insert( { _id: "01", normal: "01" } ) + +- Use a different type for member values for each distinct object, with the + same values in each object. + +- Use ``.find().sort().explain()`` for all operations. + +This scenario returns these results when using +:method:`~db.collection.find()` for different ``_id`` values; sorting with +the :operator:`$natural` operator, ``_id`` index, and ``normal`` index; +and a description of the :method:`~cursor.explain()` method output: + +.. list-table:: + :header-rows: 2 + :widths: 20 25 25 25 + + * - + - + - :method:`~cursor.sort()` + - + + * - :method:`~db.collection.find()` + - :operator:`$natural`:1 + - :term:`_id`:1 + - normal:1 + + * - :term:`_id`::doc:`ObjectId() ` + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + * - :term:`_id`::doc:`Object() ` + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + * - :term:`_id`::doc:`string() ` + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + * - :term:`_id`::doc:`integer() ` + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + * - :term:`_id`::doc:`BinData() ` + + - :method:`~cursor.explain()` scanned entire collection + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + * - normal:(any query) + + - :method:`~cursor.explain()` scanned entire collection + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor + + - :method:`~cursor.explain()` used :term:`B-Tree` cursor - .. include:: /includes/fact-natural-sort-order-text-query-restriction.rst +Additional Information +---------------------- - .. seealso:: :method:`cursor.sort()` +:method:`cursor.sort()`