> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $maxN (accumulator operator)

## Definition

Returns an aggregation of the maximum value `n` elements within a group. If the group contains fewer than `n` elements, `$maxN` returns all elements in the group.

The `$maxN` accumulator is available in these stages:

- [`$bucket`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucket.md#mongodb-pipeline-pipe.-bucket)

- [`$bucketAuto`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucketauto.md#mongodb-pipeline-pipe.-bucketAuto)

- [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group)

**Note: Other Uses of $maxN**

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

You can also use `$maxN` in these other contexts:

- [`$maxN (expression)`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/maxn-array-element.md#mongodb-expression-exp.-maxN), which returns the largest `n` values from an array.

- [`$maxN (window function)`](https://www.mongodb.com/docs/manual/reference/mql/window-functions/maxn.md#mongodb-window-window.-maxN), which is used in the [`$setWindowFields`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/setwindowfields.md#mongodb-pipeline-pipe.-setWindowFields) stage to return the largest `n` values from documents in a particular window.

## Syntax

```javascript
{
   $maxN:
      {
         input: <expression>,
         n: <expression>
      }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `input` | Expression | The expression evaluated for each element in the group. `$maxN` preserves the maximum `n` values. |
| `n` | Expression | The number of elements that `$maxN` returns from the group. For an example of setting `n` dynamically, see [Set n Based on the Group Key.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/maxn.md#std-label-max-n-with-group-key) |

## Behavior

### Result Type

When `$maxN` compares values of different types, the ordering of types follows the [BSON comparison order.](https://www.mongodb.com/docs/manual/reference/bson-type-comparison-order.md#std-label-bson-types-comparison-order)

### Null and Missing Values

`$maxN` filters out null and missing values.

The following aggregation demonstrates how `$maxN` handles null and missing values:

```javascript
db.aggregate( [
   {
      $documents: [
         { title: "Fight Club", genre: "Drama", rating: 8.9 },
         { title: "The Matrix", genre: "Drama", rating: 8.7 },
         { title: "The Green Mile", genre: "Drama", rating: 8.5 },
         { title: "Magnolia", genre: "Drama" },
         { title: "Dogma", genre: "Drama", rating: null }
      ]
   },
   {
      $group: {
         _id: "$genre",
         topFourRatings: {
            $maxN: {
               input: "$rating",
               n: 4
            }
         }
      }
   }
] )
```

**Output:**

```javascript
[
   {
      _id: 'Drama',
      topFourRatings: [ 8.9, 8.7, 8.5 ]
   }
]
```

In this example:

- [`$documents`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#mongodb-pipeline-pipe.-documents) creates the literal documents that contain movie ratings.

- [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) groups the documents by `genre`. This example has only one `genre`, `Drama`.

- `Magnolia` has a missing `rating` and `Dogma` has a null `rating`. Both values are filtered out.

- Since only 3 documents have valid ratings, `$maxN` returns 3 values even though `n = 4`.

### Comparison of $maxN and $topN Accumulators

You can use `$maxN` or [`$topN`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/topn.md#mongodb-group-grp.-topN) to return the highest-ranked `n` elements from a group. The choice between them depends on whether your input documents are already sorted.

- If the input documents are already sorted, use `$maxN` to return the maximum `n` values.

- If you need to sort and select the top `n` elements at the same time, use [`$topN`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/topn.md#mongodb-group-grp.-topN) to accomplish both with a single accumulator.

## Examples

The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). 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.

### Find the Three Highest Rated Movies for a Single Year

You can use the `$maxN` accumulator to find the three highest IMDb ratings for movies released in a single year.

```javascript
db.movies.aggregate( [
   {
      $match: {
         year: 1999,
         "imdb.rating": { $exists: true }
      }
   },
   {
      $group: {
         _id: 1999,
         topThreeRatings: {
            $maxN: {
               input: "$imdb.rating",
               n: 3
            }
         }
      }
   }
] )

```

**Output:**

```javascript
[ { _id: 1999, topThreeRatings: [ 8.9, 8.7, 8.7 ] } ]

```

The preceding pipeline:

- Uses [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) to filter for movies released in `1999` that have an `imdb.rating` field.

- Groups all matching documents into a single group with `_id: 1999`.

- Specifies `"$imdb.rating"` as the `input` for `$maxN`.

- Uses `$maxN` to return the three highest ratings with `n: 3`.

### Find the Three Highest Rated Movies Across Multiple Years

You can use the `$maxN` accumulator to find the three highest rated movies for each year in a set of years.

```javascript
db.movies.aggregate( [
   {
      $match: {
         year: { $in: [ 1999, 2000, 2001 ] },
         "imdb.rating": { $exists: true }
      }
   },
   {
      $group: {
         _id: "$year",
         topThreeRatings: {
            $maxN: {
               input: "$imdb.rating",
               n: 3
            }
         }
      }
   },
   { $sort: { _id: 1 } }
] )

```

**Output:**

```javascript
[
  { _id: 1999, topThreeRatings: [ 8.9, 8.7, 8.7 ] },
  { _id: 2000, topThreeRatings: [ 8.5, 8.5, 8.5 ] },
  { _id: 2001, topThreeRatings: [ 9.6, 9.2, 8.8 ] }
]

```

The preceding pipeline:

- Uses [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) to filter for movies released in `1999`, `2000`, or `2001` that have an `imdb.rating` field.

- Uses [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) to group movies by `year`.

- Specifies `"$imdb.rating"` as the `input` for `$maxN`.

- Uses `$maxN` to return the three highest ratings per year with `n: 3`.

- Sorts the results by year in ascending order.

### 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/cond.md#mongodb-expression-exp.-cond) expression uses the `year` field to change the value of `n`:

```javascript
db.movies.aggregate( [
   {
      $match: {
         year: { $in: [ 1999, 2000, 2001 ] },
         "imdb.rating": { $exists: true }
      }
   },
   {
      $group: {
         _id: { year: "$year" },
         topRatedMovies: {
            $maxN: {
               input: "$imdb.rating",
               n: { $cond: {
                  if: { $eq: [ "$year", 2001 ] },
                  then: 3,
                  else: 1
               } }
            }
         }
      }
   },
   { $sort: { "_id.year": 1 } }
] )

```

**Output:**

```javascript
[
  { _id: { year: 1999 }, topRatedMovies: [ 8.9 ] },
  { _id: { year: 2000 }, topRatedMovies: [ 8.5 ] },
  { _id: { year: 2001 }, topRatedMovies: [ 9.6, 9.2, 8.8 ] }
]

```

The preceding pipeline:

- Filters for movies released in `1999`, `2000`, or `2001` that have an `imdb.rating` field.

- Groups movies by `year`.

- Uses the [`$cond`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/cond.md#mongodb-expression-exp.-cond) expression to return `3` ratings for the year `2001` and `1` rating for all other years.

In the output, `2001` returns three ratings while `1999` and `2000` each return one rating.

## Learn More

- [Aggregation Pipeline Limits](https://www.mongodb.com/docs/manual/core/aggregation-pipeline-limits.md#std-label-agg-pipeline-limits)