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

# $median (accumulator operator)

## Definition

**New in version 7.0**

Returns an approximation of the median (50th [percentile](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-percentile)) value of documents in a group.

The `$median` 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: Disambiguation**

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

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

- [`$median (expression)`](https://www.mongodb.com/docs/manual/reference/expression/median.md#mongodb-expression-exp.-median), which returns the median of an array of values within a single document.

- [`$median (window function)`](https://www.mongodb.com/docs/manual/reference/mql/window-functions/median.md#mongodb-window-window.-median), 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 median value from documents in a window.

## Syntax

```javascript
{
   $median: {
      input: <number>,
      method: <string>
   }
}
```

### Command Fields

`$percentile` takes the following fields:

| Field | Type | Necessity | Description |
| --- | --- | --- | --- |
| `input` | Expression | Required | `$percentile` calculates the 50th percentile over the values returned by this expression. `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. |
| `method` | String | Required | The method that `mongod` uses to calculate the 50th percentile value. The method must be `'approximate'`. |

## Behavior

When used as an accumulator, `$median`:

- Calculates a single result for all the 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 the median using a data structure of bounded size.

### Calculation Considerations

When used as an accumulator, `$median` always uses an approximation algorithm. As a result, the computed percentiles `$median` returns on the same data set might differ on each run, due to pseudorandomness in the t-digest approximation algorithm. Additionally, `$median` may return a value that differs slightly from the true statistical median.

## 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.

The following example uses `$median` to calculate the median IMDb rating of Action movies per year from 2000 to 2004:

```shell
db.movies.aggregate( [
   {
      $match: {
         genres: "Action",
         year: { $gte: 2000, $lte: 2004 },
         "imdb.rating": { $gt: 0 }
      }
   },
   {
      $group: {
         _id: "$year",
         medianRating: {
            $median: {
               input: "$imdb.rating",
               method: "approximate"
            }
         }
      }
   },
   { $sort: { _id: 1 } }
] )

```

**Output:**

```shell
[
  { _id: 2000, medianRating: 6.4 },
  { _id: 2001, medianRating: 6.4 },
  { _id: 2002, medianRating: 6.2 },
  { _id: 2003, medianRating: 6.4 },
  { _id: 2004, medianRating: 6.5 }
]

```

In the preceding pipeline:

- [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) filters for Action movies released between 2000 and 2004 with a valid IMDb rating.

- [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) groups documents by `year` and uses `$median` to calculate the median `imdb.rating` across all Action movies in each year.

- [`$sort`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#mongodb-pipeline-pipe.-sort) sorts the results by year in ascending order.

## Learn More

- [`$median (expression)`](https://www.mongodb.com/docs/manual/reference/expression/median.md#mongodb-expression-exp.-median)

- [`$median (window function)`](https://www.mongodb.com/docs/manual/reference/mql/window-functions/median.md#mongodb-window-window.-median)

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