/ /

$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