$firstN (accumulator operator)

Definition

$firstN

Returns an aggregation of the first n elements in a group. The results are meaningful only if the input data to the grouping stage has a defined sort order. If the group contains fewer than n elements, $firstN returns all elements in the group.

The $firstN accumulator is available in these stages:

Note

Disambiguation

This page describes $firstN when used as an accumulator. Accumulators return a single aggregated value like sum, maximum, or minimum across a group of input documents.

You can also use $firstN in these other contexts:

$firstN (expression), which returns the specified number of elements from the beginning of an array.
$firstN (window function), which is used in the $setWindowFields stage to return the first n values from documents in a particular window.

Syntax

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

Options

Field	Type	Description
`input`	Expression	The `input` expression is evaluated over each document in the input group, and the first `n` results are preserved.
`n`	Expression	The number of elements that `$firstN` returns from the group. For an example of setting `n` dynamically based on the group key, see Set n Based on the Group Key.

Behavior

Null and Missing Values

$firstN does not filter out null values.
$firstN converts missing values to null.

Comparison of $firstN and $topN

Both $firstN and $topN accumulators can accomplish similar results.

In general:

If the documents coming into $group are already ordered, you should use $firstN.
If you're sorting and selecting the top n elements then you can use $topN to accomplish both tasks with one accumulator.

Examples

The examples on this page use the movies collection in the sample_mflix sample dataset. To learn how to load the sample dataset into your MongoDB deployment, see Import Sample Data Into Your Atlas Deployment.

Find the First Three Movies for a Single Genre

You can use the $firstN accumulator to find the first three movies in a single genre.

db.movies.aggregate( [   {      $match: { genres: "Horror" }   },   {          $sort: { year: 1 }   },   {      $group:         {            _id: "Horror",            firstThreeMovies:               {                  $firstN:                  {                     input: [ "$title", "$year" ],                     n: 3                  }               }         }   }] )

[  {    _id: 'Horror',    firstThreeMovies: [      [ 'Dr. Jekyll and Mr. Hyde', 1931 ],      [ 'Dracula', 1931 ],      [ 'The Black Cat', 1934 ]    ]  }]

The preceding pipeline:

Uses $match to filter the results to movies where Horror is included in the genres array.
Sorts the results by year in ascending order.
Groups all resulting documents into a single group.
Specifies the fields that are input for $firstN with input : ["$title", "$year"].
Uses $firstN to return the first three documents for the Horror genre with n: 3.

Find the First Three Movies Across Multiple Genres

You can use the $firstN accumulator to find the first n input fields in each genre.

db.movies.aggregate( [   {      $unwind: "$genres"   },   {      $sort: { year: 1 }   },   {      $group:         {            _id: "$genres",            movies:               {                  $firstN:                     {                        input: [ "$title", "$year" ],                        n: 3                     }               }         }   },   { $sort: { _id: 1 } },   { $limit: 5 }] )

[  {    _id: 'Action',    movies: [      [ 'The Perils of Pauline', 1914 ],      [ 'From Hand to Mouth', 1919 ],      [ "For Heaven's Sake", 1926 ]    ]  },  {    _id: 'Adventure',    movies: [      [ 'Robin Hood', 1922 ],      [ 'Peter Pan', 1924 ],      [ 'The Thief of Bagdad', 1924 ]    ]  },  {    _id: 'Animation',    movies: [      [        'Winsor McCay, the Famous Cartoonist of the N.Y. Herald and His Moving Comics',        1911      ],      [        'Winsor McCay, the Famous Cartoonist of the N.Y. Herald and His Moving Comics',        1911      ],      [ 'Gertie the Dinosaur', 1914 ]    ]  },  {    _id: 'Biography',    movies: [ [ 'Regeneration', 1915 ], [ 'Salomè', 1922 ], [ 'Napoleon', 1927 ] ]  },  {    _id: 'Comedy',    movies: [      [        'Winsor McCay, the Famous Cartoonist of the N.Y. Herald and His Moving Comics',        1911      ],      [        'Winsor McCay, the Famous Cartoonist of the N.Y. Herald and His Moving Comics',        1911      ],      [ 'Gertie the Dinosaur', 1914 ]    ]  }]

The preceding pipeline:

Uses $unwind to create a separate document for each genre in the genres array.
Sorts the results by year in ascending order.
Uses $group to group the results by genres.
Uses $firstN to return the first three documents for each genre with n: 3.
Specifies the fields that are input for $firstN with input : ["$title", "$year"].
Limits the output to five documents to improve readability.

Set n Based on the Group Key

You can assign the value of n dynamically based on the group key. In this example, the $cond expression uses the rated field to change the value of n:

db.movies.aggregate([   { $match: { rated: { $in: ["G", "PG", "PG-13", "R"] } } },   { $sort: { title: 1 } },   {      $group:         {            _id: {"rated": "$rated"},            movies:               {                  $firstN:                     {                        input: "$title",                        n: { $cond: { if: { $eq: ["$rated", "PG"] }, then: 3, else: 1 } }                     }               }         }   }] )

[  { _id: { rated: 'PG-13' }, movies: [ "'night, Mother" ] },  {    _id: { rated: 'PG' },    movies: [ '*batteries not included', '...And God Created Woman', '1776' ]  },  { _id: { rated: 'G' }, movies: [ '101 Dalmatians' ] },  { _id: { rated: 'R' }, movies: [ '$' ] }]

The preceding pipeline:

Filters for movies with ratings of G, PG, PG-13, or R.
Sorts the results alphabetically by title.
Groups movies by rated (the movie rating).
Uses the $cond expression to return 3 movies for PG-rated movies and 1 movie for all other ratings.

In the output, the PG rating returns 3 movies, while G, PG-13, and R ratings each return 1 movie.

Learn More

Back

$first

$last