@@ -4,11 +4,14 @@ $natural
4
4
5
5
.. default-domain:: mongodb
6
6
7
+ Definition
8
+ ----------
9
+
7
10
.. operator:: $natural
8
11
9
12
Use the :operator:`$natural` operator to use :term:`natural order` for
10
13
the results of a sort operation. Natural order refers to the
11
- order of documents in the file on disk.
14
+ :ref:`storage order <return-storage-order>` of documents in the file on disk.
12
15
13
16
The :operator:`$natural` operator uses the following syntax to return
14
17
documents in the order they exist on disk:
@@ -17,13 +20,116 @@ $natural
17
20
18
21
db.collection.find().sort( { $natural: 1 } )
19
22
20
- Use ``-1`` to return documents in the reverse order as they occur on
21
- disk:
23
+ Behavior
24
+ --------
25
+
26
+ On a sharded collection the :operator:`$natural` operator returns a
27
+ collection scan sorted in :ref:`storage order<return-storage-order>`, the
28
+ order the database inserts and stores documents on disk.
29
+
30
+ .. include:: /includes/fact-natural-parameter.rst
31
+
32
+ .. include:: /includes/fact-natural-sort-order-text-query-restriction.rst
33
+
34
+ Examples
35
+ --------
36
+
37
+ Reverse Order
38
+ ~~~~~~~~~~~~~
39
+
40
+ Use ``-1`` to return documents in the reverse order as they occur on disk:
41
+
42
+ .. code-block:: javascript
43
+
44
+ db.collection.find().sort( { $natural: -1 } )
45
+
46
+ Natural Order Comparison
47
+ ~~~~~~~~~~~~~~~~~~~~~~~~
48
+
49
+ In this scenario:
50
+
51
+ - Create an extra index as { normal: 1 }.
52
+
53
+ - Insert relevant objects with ``_id`` and ``normal`` values, for example,
54
+ a string type object created with:
22
55
23
56
.. code-block:: javascript
24
57
25
- db.collection.find().sort( { $natural: -1 } )
58
+ db.coll.insert( { _id: "01", normal: "01" } )
59
+
60
+ - Use a different type for member values for each distinct object, with the
61
+ same values in each object.
62
+
63
+ - Use ``.find().sort().explain()`` for all operations.
64
+
65
+ This scenario returns these results when using
66
+ :method:`~db.collection.find()` for different ``_id`` values; sorting with
67
+ the :operator:`$natural` operator, ``_id`` index, and ``normal`` index;
68
+ and a description of the :method:`~cursor.explain()` method output:
69
+
70
+ .. list-table::
71
+ :header-rows: 2
72
+ :widths: 20 25 25 25
73
+
74
+ * -
75
+ -
76
+ - :method:`~cursor.sort()`
77
+ -
78
+
79
+ * - :method:`~db.collection.find()`
80
+ - :operator:`$natural`:1
81
+ - :term:`_id`:1
82
+ - normal:1
83
+
84
+ * - :term:`_id`::doc:`ObjectId() </reference/bson-types>`
85
+
86
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
87
+
88
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
89
+
90
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
91
+
92
+ * - :term:`_id`::doc:`Object() </reference/bson-types>`
93
+
94
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
95
+
96
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
97
+
98
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
99
+
100
+ * - :term:`_id`::doc:`string() </reference/bson-types>`
101
+
102
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
103
+
104
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
105
+
106
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
107
+
108
+ * - :term:`_id`::doc:`integer() </reference/bson-types>`
109
+
110
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
111
+
112
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
113
+
114
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
115
+
116
+ * - :term:`_id`::doc:`BinData() </reference/bson-types>`
117
+
118
+ - :method:`~cursor.explain()` scanned entire collection
119
+
120
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
121
+
122
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
123
+
124
+ * - normal:(any query)
125
+
126
+ - :method:`~cursor.explain()` scanned entire collection
127
+
128
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
129
+
130
+ - :method:`~cursor.explain()` used :term:`B-Tree` cursor
26
131
27
- .. include:: /includes/fact-natural-sort-order-text-query-restriction.rst
132
+ Additional Information
133
+ ----------------------
28
134
29
- .. seealso:: :method:`cursor.sort()`
135
+ :method:`cursor.sort()`
0 commit comments