$firstN (expression)

Definition

$firstN

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

Syntax

{ $firstN: { input: <expression>, n: <expression> } }

Behavior

• $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 entire input array.

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

Example

The examples on this page use data from the sample_mflix dataset. For details on how to load this dataset into your self-managed MongoDB deployment, see Load the Sample Dataset. If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

The following example uses the $firstN operator to return the first three cast members for each movie. The cast members are returned in the new field firstThreeCast created by $addFields.

db.movies.aggregate( [
   {
      $match: {
         title: { $in: [ "The Godfather", "Spirited Away", "The Dark Knight" ] }
      }
   },
   {
      $addFields: {
         firstThreeCast: { $firstN: { input: "$cast", n: 3 } }
      }
   },
   {
      $project: {
         _id: 0,
         title: 1,
         cast: 1,
         firstThreeCast: 1
      }
   },
   {
      $sort: { title: 1 }
   }
] )

[
  {
    title: 'Spirited Away',
    cast: [ 'Rumi Hiiragi', 'Miyu Irino', 'Mari Natsuki', 'Takashi Naitè' ],
    firstThreeCast: [ 'Rumi Hiiragi', 'Miyu Irino', 'Mari Natsuki' ]
  },
  {
    title: 'The Dark Knight',
    cast: [ 'Christian Bale', 'Heath Ledger', 'Aaron Eckhart', 'Michael Caine' ],
    firstThreeCast: [ 'Christian Bale', 'Heath Ledger', 'Aaron Eckhart' ]
  },
  {
    title: 'The Godfather',
    cast: [ 'Marlon Brando', 'Al Pacino', 'James Caan', 'Richard S. Castellano' ],
    firstThreeCast: [ 'Marlon Brando', 'Al Pacino', 'James Caan' ]
  }
]

The preceding pipeline:

• Uses $match to filter for three specific movies.

• Uses $addFields with $firstN to create a new field firstThreeCast containing the first three elements from the cast array with n: 3.

• Uses $project to include only the title, cast, and firstThreeCast fields in the output.

• Uses $sort to sort the results by title.

Learn More

• $lastN

• $sortArray