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

# $percentile (accumulator operator)

## Definition

**New in version 7.0**

Returns an array of scalar values that correspond to specified [percentile](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-percentile) values.

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: Disambiguation**

This page describes `$percentile` when used as an **accumulator**. Accumulators return an aggregated value across a group of input documents.

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

- [`$percentile (expression)`](https://www.mongodb.com/docs/manual/reference/expression/percentile.md#mongodb-expression-exp.-percentile), which calculates percentile values over an array of input values.

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

## Syntax

```javascript
{
   $percentile: {
      input: <expression>,
      p: [ <expression1>, <expression2>, ... ],
      method: <string>
   }
}
```

### Options

`$percentile` takes the following fields:

| Field | Type | Necessity | Description |
| --- | --- | --- | --- |
| `input` | Expression | Required | `$percentile` calculates the percentile values of this data. `input` must be an expression that evaluates to a numeric type. If the expression does not evaluate to a numeric type, the `$percentile` calculation ignores that value. |
| `p` | Expression | Required | `$percentile` calculates a percentile value for each element in `p`. These elements specify the quantiles to compute and must be numeric values in the range `0.0` to `1.0`, inclusive. `$percentile` returns results in the same order as the elements in `p`. |
| `method` | String | Required | The method that MongoDB uses to calculate the percentile value. The method must be `'approximate'`. |

## Behavior

When used as an accumulator, `$percentile`:

- Calculates one set of percentiles per group, aggregated across all documents in the group.

- Uses the [t-digest](https://arxiv.org/abs/1902.04023) algorithm for calculation of approximate percentiles. Approximation is necessary to calculate percentiles using a data structure of bounded size.

### Calculation Considerations

When used as an accumulator, `$percentile` always uses an approximation algorithm. Due to pseudorandomness in the t-digest approximation algorithm, the computed percentile values on the same data set might differ on each run. Additionally, `$percentile` may return values that differ slightly from the true statistical percentiles.

## Example

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.

### Calculate Rating Percentiles by Genre

The following example uses the `$percentile` accumulator to calculate the 50th and 90th percentile IMDB ratings for movies in the `Action` and `Drama` genres:

```javascript
db.movies.aggregate( [
   {
      $unwind: "$genres"
   },
   {
      $match: {
         genres: { $in: [ "Action", "Drama" ] },
         "imdb.rating": { $exists: true }
      }
   },
   {
      $group: {
         _id: "$genres",
         ratingPercentiles: {
            $percentile: {
               input: "$imdb.rating",
               p: [ 0.5, 0.9 ],
               method: "approximate"
            }
         }
      }
   },
   {
      $sort: { _id: 1 }
   }
] )

```

**Output:**

```javascript
[
  { _id: 'Action', ratingPercentiles: [ 6.5, 7.6 ] },
  { _id: 'Drama', ratingPercentiles: [ 6.9, 7.8 ] }
]

```

The preceding pipeline:

- Uses [`$unwind`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind.md#mongodb-pipeline-pipe.-unwind) to create a separate document for each genre in the `genres` array.

- Uses [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) to filter for movies that are classified as `Action` or `Drama` and have an IMDB rating field.

- Groups movies by genre.

- Uses `$percentile` to calculate the 50th and 90th percentile IMDB ratings for each genre with `p: [0.5, 0.9]`.

- Uses [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort) to order the output by genre name.

The output `ratingPercentiles` array contains two values: the 50th percentile and the 90th percentile IMDB rating for each genre.