Docs Menu
Docs Home
/
MongoDB Manual
/ / /

$firstN (array operator)

On this page

  • Definition
  • Syntax
  • Behavior
  • Example
$firstN

New in version 5.2.

Returns a specified number of elements from the beginning of an array.

Tip

See also:

  • $lastN

  • $sortArray

$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.
  • $firstN returns elements in the same order they appear in the input array.

  • $firstN does not filter out null values in the input array.

  • You cannot specify a value of n less than 1.

  • If the specified n is greater than or equal to the number of elements in the input array, $firstN returns the input array.

  • If input resolves to a non-array value, the aggregation operation errors.

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") ]
}]

Back

$firstN (aggregation accumulator)