$minN (aggregation accumulator)

Result Type

When $minN compares values of different types, the ordering of types follows the BSON comparison order.

Null and Missing Values

$minN filters out null and missing values.

Consider the following aggregation that returns the minimum n values from a group:

db.aggregate( [
   {
      $documents: [
         { playerId: "PlayerA", gameId: "G1", score: 1 },
         { playerId: "PlayerB", gameId: "G1", score: 2 },
         { playerId: "PlayerC", gameId: "G1", score: 3 },
         { playerId: "PlayerD", gameId: "G1" },
         { playerId: "PlayerE", gameId: "G1", score: null }
      ]
   },
   {
      $group:
      {
         _id: "$gameId",
         minimumThreeScores:
            {
               $minN:
                  {
                     input: "$score",
                     n: 4
                  }
            }
      }
   }
] )

In this example:

• $documents creates the literal documents that contain player scores.

• $group groups the documents by gameId. This example has only one gameId, G1.

• PlayerD has a missing score and PlayerE has a null score. These values are both ignored.

• The minimumThreeScores field is specified as $minN with input : "$score" and returned as an array.

• Since there are only 3 documents with scores, $minN returns the minimum 3 score fields even though n = 4.

[
   {
   _id: 'G1',
   minimumThreeScores: [ 1, 2, 3 ]
   }
]

Comparison of $minN and $bottomN Accumulators

Both $minN and $bottomN accumulators return n values from a group, but they differ in how they determine which values to return.

• Use $minN when the values you want to compare are the same values you want to return. $minN selects the n smallest values by comparing inputs directly.

• Use $bottomN when you want to define the sort order separately from the output. $bottomN lets you specify a sortBy key to determine which documents are "bottom" and an output expression to control what values to return.

Find the Minimum Three Ratings for a Single Genre

You can use the $minN accumulator to find the three lowest IMDb ratings in a single genre.

db.movies.aggregate( [
   {
      $match: { genres: "Horror" }
   },
   {
      $group:
         {
            _id: "Horror",
            minThreeRatings:
               {
                  $minN:
                  {
                     input: "$imdb.rating",
                     n: 3
                  }
               }
         }
   }
] )

[ { _id: 'Horror', minThreeRatings: [ 2, 2, 2.2 ] } ]

The example pipeline:

• Uses $match to filter the results to movies where Horror is included in the genres array.

• Uses $group to group all matching documents into a single group.

• Specifies the input for $minN with input: "$imdb.rating".

• Uses $minN to return the three lowest IMDb rating entries for the Horror genre with n: 3.

Find the Minimum Three Ratings Across Multiple Genres

You can use the $minN accumulator to find the minimum n IMDb ratings in each genre.

db.movies.aggregate( [
   {
      $unwind: "$genres"
   },
   {
      $group:
         {
            _id: "$genres",
            minThreeRatings:
               {
                  $minN:
                     {
                        input: "$imdb.rating",
                        n: 3
                     }
               }
         }
   },
   { $sort: { _id: 1 } },
   { $limit: 5 }
] )

[
  { _id: 'Action', minThreeRatings: [ 2, 2, 2.1 ] },
  { _id: 'Adventure', minThreeRatings: [ 2.1, 2.3, 2.4 ] },
  { _id: 'Animation', minThreeRatings: [ 2.7, 4, 4.1 ] },
  { _id: 'Biography', minThreeRatings: [ 2.3, 2.7, 3.5 ] },
  { _id: 'Comedy', minThreeRatings: [ 1.6, 1.9, 1.9 ] }
]

The example pipeline:

• Uses $unwind to create a separate document for each genre in the genres array.

• Uses $group to group the results by genres.

• Uses $minN to return the three lowest IMDb rating entries for each genre with n: 3.

• Specifies the input for $minN with input: "$imdb.rating".

• Uses $sort to sort the results alphabetically by genre.

• Limits the output to five documents to improve readability.

Set n Dynamically Based on the Group Key

You can assign the value of n dynamically. In this example, the $cond expression is used on the rated field.

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

[
  { _id: { rated: 'PG' }, minMovies: [ 1.6 ] },
  { _id: { rated: 'G' }, minMovies: [ 1.6 ] },
  { _id: { rated: 'R' }, minMovies: [ 2, 2.2, 2.2 ] },
  { _id: { rated: 'PG-13' }, minMovies: [ 1.9 ] }
]

The example pipeline:

• Filters for movies with ratings of G, PG, PG-13, or R.

• Groups movies by rated (the content rating).

• Specifies the input for $minN with input: "$imdb.rating".

• Uses the $cond expression to return 3 minimum entries for R-rated movies and 1 minimum entry for all other ratings.

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