$stdDevPop (aggregation)¶

On this page

Definition¶

$stdDevPop¶

New in version 3.2.

Calculates the population standard deviation of the input values. Use if the values encompass the entire population of data you want to represent and do not wish to generalize about a larger population. $stdDevPop ignores non-numeric values.

If the values represent only a sample of a population of data from which to generalize about the population, use $stdDevSamp instead.

$stdDevPop is available in the $group and $project stages.

When used in the $group stage, $stdDevPop returns the population standard deviation of the specified expression for a group of documents that share the same group by key and has the following syntax:

$stdDevPop has one specified expression as its operand:
```
{ $stdDevPop: <expression> }
```

When used in the $project stage, $stdDevPop returns the standard deviation of the specified expression or list of expressions for each document and has one of two syntaxes:

$stdDevPop has one specified expression as its operand:
```
{ $stdDevPop: <expression> }
```

$stdDevPop has a list of specified expressions as its operand:

{ $stdDevPop: [ <expression1>, <expression2> ... ]  }

The argument for $stdDevPop can be any expression as long as it resolves to an array. For more information on expressions, see Expressions

Behavior¶

Non-numeric Values¶

$stdDevPop ignores non-numeric values. If all operands for a $stdDevPop are non-numeric, $stdDevPop returns null.

Single Value¶

If the sample consists of a single numeric value, $stdDevPop returns 0.

Array Operand¶

In the $group stage, if the expression resolves to an array, $stdDevPop treats the operand as a non-numerical value.

In the $project stage:

With a single expression as its operand, if the expression resolves to an array, $stdDevPop traverses into the array to operate on the numerical elements of the array to return a single value.
With a list of expressions as its operand, if any of the expressions resolves to an array, $stdDevPop does not traverse into the array but instead treats the array as a non-numerical value.

Examples¶

Use in `$group` Stage¶

A collection named users contains the following documents:

{ "_id" : 1, "name" : "dave123", "quiz" : 1, "score" : 85 }
{ "_id" : 2, "name" : "dave2", "quiz" : 1, "score" : 90 }
{ "_id" : 3, "name" : "ahn", "quiz" : 1, "score" : 71 }
{ "_id" : 4, "name" : "li", "quiz" : 2, "score" : 96 }
{ "_id" : 5, "name" : "annT", "quiz" : 2, "score" : 77 }
{ "_id" : 6, "name" : "ty", "quiz" : 2, "score" : 82 }

The following example calculates the standard deviation of each quiz:

db.users.aggregate([
   { $group: { _id: "$quiz", stdDev: { $stdDevPop: "$score" } } }
])

The operation returns the following results:

{ "_id" : 2, "stdDev" : 8.04155872120988 }
{ "_id" : 1, "stdDev" : 8.04155872120988 }

Use in `$project` Stage¶

A collection named quizzes contains the following documents:

{
   "_id" : 1,
   "scores" : [
      {
         "name" : "dave123",
         "score" : 85
      },
      {
         "name" : "dave2",
         "score" : 90
      },
      {
         "name" : "ahn",
         "score" : 71
      }
   ]
}
{
   "_id" : 2,
   "scores" : [
      {
         "name" : "li",
         "quiz" : 2,
         "score" : 96
      },
      {
         "name" : "annT",
         "score" : 77
      },
      {
         "name" : "ty",
         "score" : 82
      }
   ]
}