$median (aggregation)

Type of Operation

In a $group stage, $median is an accumulator and calculates a value for all documents in the window.

In a $project stage, $median is an aggregation expression and calculates values for each document.

In $setWindowFields stages, $median returns a result for each document like an aggregation expression, but the results are computed over groups of documents like an accumulator.

Calculation Considerations

In $group stages, $median always uses an approximate calculation method.

In $project stages, $median might use the discrete calculation method even when the approximate method is specified.

In $setWindowFields stages, the workload determines the calculation method that $median uses.

The computed percentiles $median returns might vary, even on the same datasets. This is because the algorithm calculates approximate values.

Duplicate samples can cause ambiguity. If there are a large number of duplicates, the percentile values may not represent the actual sample distribution. Consider a data set where all the samples are the same. All of the values in the data set fall at or below any percentile. A "50th percentile" value would actually represent either 0 or 100 percent of the samples.

Array Input

If you use $median as an aggregation expression in a $project stage, you can use an array as input. $median ignores non-numeric array values.

The syntax is:

{
   $median:
      {
         input: [ <expression1, <expression2>, ..., <expressionN> ],
         method: <string>
      }
}

Window Functions

A window function lets you calculate results over a moving "window" of neighboring documents. As each document passes though the pipeline, the $setWindowFields stage:

• Recomputes the set of documents in the current window

• calculates a value for all documents in the set

• returns a single value for that document

You can use $median in a $setWindowFields stage to calculate rolling statistics for time series or other related data.

When you use $median in a $setWindowField stage, the input value must be a field name. If you enter an array instead of a field name, the operation fails.

Use $median as an Accumulator

Create an accumulator that calculates the median value:

db.testScores.aggregate( [
   {
      $group: {
         _id: null,
         test01_median: {
            $median: {
               input: "$test01",
               method: 'approximate'
            }
         }
      }
   }
] )

Output:

{ _id: null, test01_median: 62 }

The _id field value is null so $group selects all the documents in the collection.

The $median accumulator takes its input from the test01 field. $median calculates the median value for the field, 62 in this example.

Use $median in a $project Stage

In a $group stage, $median is an accumulator and calculates a single value for all documents. In a $project stage, $median is an aggregation expression and calculates values for each document.

You can use a field name or an array as input in a $project stage.

db.testScores.aggregate( [
   {
      $project: {
         _id: 0,
         studentId: 1,
         testMedians: {
            $median: {
               input: [ "$test01", "$test02", "$test03" ],
               method: 'approximate'
            }
         }
      }
   }
] )

Output:

{ studentId: '2345', testMedians: 80 },
{ studentId: '2356', testMedians: 79 },
{ studentId: '2358', testMedians: 78 },
{ studentId: '2367', testMedians: 72 },
{ studentId: '2369', testMedians: 60 }

When $median is an aggregation expression there is a result for each studentId.

Use $median in a $setWindowField Stage

To base your percentile values on local data trends, use $median in a $setWindowField aggregation pipeline stage.

This example creates a window to filter scores:

db.testScores.aggregate( [
   {
      $setWindowFields: {
         sortBy: { test01: 1 },
         output: {
            test01_median: {
               $median: {
                  input: "$test01",
                  method: 'approximate'
               },
               window: {
                  range: [ -3, 3 ]
               }
            }
         }
      }
   },
   {
      $project: {
         _id: 0,
         studentId: 1,
         test01_median: 1
      }
   }
] )

Output:

{ studentId: '2356', test01_median: 60 },
{ studentId: '2369', test01_median: 60 },
{ studentId: '2345', test01_median: 60 },
{ studentId: '2367', test01_median: 64 },
{ studentId: '2358', test01_median: 64 }

In this example, the median calculation for each document also incorporates data from the three documents before and after it.