- Reference >
- Operators >
- Aggregation Pipeline Operators >
- $rank (aggregation)
$rank (aggregation)¶
On this page
Definition¶
New in version 5.0.
-
$rank¶
Returns the document position (known as the rank) relative to other
documents in the $setWindowFields stage partition.
The $setWindowFields stage sortBy field value determines the document rank. For
more information on how MongoDB compares fields with different types,
see BSON comparison order.
If multiple documents occupy the same rank, $rank places
the document with the subsequent value at a rank with a gap
(see Behavior).
$rank is only available in the $setWindowFields
stage.
$rank syntax:
$rank does not accept any parameters.
See also
Behavior¶
$rank and $denseRank differ in how they rank duplicate
sortBy field values. For example, with
sortBy field values of 7, 9, 9, and 10:
$denseRankranks the values as 1, 2, 2, and 3. The duplicate 9 values have a rank of 2, and 10 has a rank of 3. There is no gap in the ranks.$rankranks the values as 1, 2, 2, and 4. The duplicate 9 values have a rank of 2, and 10 has a rank of 4. There is a gap in the ranks for 3.
Documents with a null value for a sortBy field or documents missing the sortBy field are assigned a rank based on the
BSON comparison order.
See the example in Rank Partitions Containing Duplicate Values, Nulls, or Missing Data.
Examples¶
Create a cakeSales collection that contains cake sales in the states
of California (CA) and Washington (WA):
Rank Partitions by an Integer Field¶
This example uses $rank in the $setWindowFields
stage to output the quantity rank of the cake sales for each
state:
In the example:
partitionBy: "$state"partitions the documents in the collection bystate. There are partitions forCAandWA.sortBy: { quantity: -1 }sorts the documents in each partition byquantityin descending order (-1), so the highestquantityis first.outputsets therankQuantityForStatefield to thequantityrank using$rank, as shown in the following results.
Rank Partitions by a Date Field¶
This example shows how to use dates with $rank in the
$setWindowFields stage to output the orderDate rank of
the cake sales for each state:
In the example:
partitionBy: "$state"partitions the documents in the collection bystate. There are partitions forCAandWA.sortBy: { orderDate: 1 }sorts the documents in each partition byorderDatein ascending order (1), so the earliestorderDateis first.outputsets therankOrderDateForStatefield to theorderDaterank using$rank, as shown in the following results.
Rank Partitions Containing Duplicate Values, Nulls, or Missing Data¶
Create a cakeSalesWithDuplicates collection where:
- Cake sales are placed in the state of California (
CA) and Washington (WA). - Documents 6 to 8 have the same
quantityandstateas document 5. - Document 9 has the same
quantityandstateas document 4. - Document 10 has a
nullquantity. - Document 11 is missing the
quantity.
This example uses $rank in the $setWindowFields
stage to output the quantity rank from the
cakeSalesWithDuplicates collection for each state:
In the example:
partitionBy: "$state"partitions the documents in the collection bystate. There are partitions forCAandWA.sortBy: { quantity: -1 }sorts the documents in each partition byquantityin descending order (-1), so the highestquantityis first.outputsets therankOrderDateForStatefield to thequantityrank using$rank.
In the following example output:
- Documents with the same
quantityandstatehave the same rank. If documents have the same rank, there is a gap between that rank and the next rank. - The document with the
nullquantityand then the document with the missingquantityare ranked the lowest in the output for theCApartition. This sorting is the result of the BSON comparison order, which sortsnulland missing values after number values in this example.