- Reference >
mongo
Shell Methods >- Cursor Methods >
- cursor.sort()
cursor.sort()¶
On this page
Definition¶
-
cursor.
sort
(sort)¶ Controls the order that the query returns matching documents. For each field in the sort document, if the field’s corresponding value is positive, then
sort()
returns query results in ascending order for that attribute. If the field’s corresponding value is negative, thensort()
returns query results in descending order.The
sort()
method has the following parameter:Parameter Type Description sort
document A document that defines the sort order of the result set. The
sort
parameter contains field and value pairs, in the following form:field
is the field by which to sort documents.value
is either 1 for ascending or -1 for descending.
Note
You must apply
sort()
to the cursor before retrieving any documents from the database.
Behavior¶
Sort Order¶
When comparing values of different BSON types, MongoDB uses the following comparison order, from lowest to highest:
- MinKey (internal type)
- Null
- Numbers (ints, longs, doubles)
- Symbol, String
- Object
- Array
- BinData
- ObjectId
- Boolean
- Date, Timestamp
- Regular Expression
- MaxKey (internal type)
MongoDB treats some types as equivalent for comparison purposes. For instance, numeric types undergo conversion before comparison.
The comparison treats a non-existent field as it would an empty BSON
Object. As such, a sort on the a
field in documents { }
and {
a: null }
would treat the documents as equivalent in sort order.
With arrays, a less-than comparison or an ascending sort compares the
smallest element of arrays, and a greater-than comparison or a
descending sort compares the largest element of the arrays. As such,
when comparing a field whose value is a single-element array (e.g. [
1 ]
) with non-array fields (e.g. 2
), the comparison is between
1
and 2
. A comparison of an empty array (e.g. [ ]
) treats
the empty array as less than null
or a missing field.
Limit Results¶
The sort operation requires that the entire sort be able to complete within 32 megabytes.
When the sort operation consumes more than 32 megabytes, MongoDB
returns an error. To avoid this error, either create an index to
support the sort operation or use sort()
in
conjunction with limit()
. The specified limit must
result in a number of documents that fall within the 32 megabyte limit.
For example, if the following sort operation stocks_quotes
exceeds
the 32 megabyte limit:
Either create an index to support the sort operation:
Interaction with Projection¶
When a set of results are both sorted and projected, the MongoDB query engine will always apply the sorting first.
Examples¶
A collection orders
contain the following documents:
The following query, which returns all documents from the orders
collection, does not specify a sort order:
The query returns the documents in indeterminate order:
The following query specifies a sort on the amount
field in
descending order.
The query returns the following documents, in descending order of
amount
:
The following query specifies the sort order using the fields from a
sub-document item
. The query sorts first by the category
field
in ascending order, and then within each category
, by the type
field in ascending order.
The query returns the following documents, ordered first by the
category
field, and within each category, by the type
field:
Return in Natural Order¶
The $natural
parameter returns items according to their
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 natural order reflects insertion order, except when documents relocate because of document growth due to updates or remove operations free up space which are then taken up by newly inserted documents.
Consider the sequence of insert operations to the trees
collection:
The following query returns the documents in the natural order:
The documents return in the following order:
Update a document such that the document outgrows its current allotted space:
Rerun the query to returns the documents in natural order:
The documents return in the following natural order:
See also