$firstN (array operator)
On this page
Definition
$firstNNew in version 5.2.
Returns a specified number of elements from the beginning of an array.
Tip
See also:
Syntax
$firstN has the following syntax:
{ $firstN: { n: <expression>, input: <expression> } }
Field | Description |
|---|---|
n | An expression that resolves to a
positive integer. The integer specifies the number of array elements
that $firstN returns. |
input | An expression that resolves to the
array from which to return n elements. |
Behavior
$firstNreturns elements in the same order they appear in the input array.$firstNdoes not filter outnullvalues in the input array.You cannot specify a value of
nless than1.If the specified
nis greater than or equal to the number of elements in theinputarray,$firstNreturns theinputarray.If
inputresolves to a non-array value, the aggregation operation errors.
Example
The collection games has the following documents:
db.games.insertMany([ { "playerId" : 1, "score" : [ 1, 2, 3 ] }, { "playerId" : 2, "score" : [ 12, 90, 7, 89, 8 ] }, { "playerId" : 3, "score" : [ null ] }, { "playerId" : 4, "score" : [ ] }, { "playerId" : 5, "score" : [ 1293, null, 3489, 9 ]}, { "playerId" : 6, "score" : [ "12.1", 2, NumberLong("2090845886852"), 23 ]} ])
The following example uses the $firstN operator to retrieve the
first three scores for each player. The scores are returned in the new field
firstScores created by $addFields.
db.games.aggregate([ { $addFields: { firstScores: { $firstN: { n: 3, input: "$score" } } } } ])
The operation returns the following results:
[{ "playerId": 1, "score": [ 1, 2, 3 ], "firstScores": [ 1, 2, 3 ] }, { "playerId": 2, "score": [ 12, 90, 7, 89, 8 ], "firstScores": [ 12, 90, 7 ] }, { "playerId": 3, "score": [ null ], "firstScores": [ null ] }, { "playerId": 4, "score": [ ], "firstScores": [ ] }, { "playerId": 5, "score": [ 1293, null, 3489, 9 ], "firstScores": [ 1293, null, 3489 ] }, { "playerId": 6, "score": [ "12.1", 2, NumberLong("2090845886852"), 23 ], "firstScores": [ "12.1", 2, NumberLong("2090845886852") ] }]