Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

$stdDevPop (aggregation)

On this page

  • Definition
  • Syntax
  • Behavior
  • Examples
$stdDevPop

Changed in version 5.0.

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 these stages:

When used in the $bucket, $bucketAuto, $group, and $setWindowFields stages, $stdDevPop has this syntax:

{ $stdDevPop: <expression> }

When used in other supported stages, $stdDevPop 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 Expression Operators.

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

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

In the $group and $setWindowFields stages, if the expression resolves to an array, $stdDevPop treats the operand as a non-numerical value and has no effect on the calculation.

In the other supported stages:

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

Behavior with values in a $setWindowFields stage window:

  • Ignores non-numeric values, null values, and missing fields in a window.

  • If the window is empty, returns null.

  • If the window contains a NaN value, returns null.

  • If the window contains Infinity values, returns null.

  • If none of the previous points apply, returns a double value.

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 }

Create an example collection named quizzes with the following documents:

db.quizzes.insertMany([
{
"_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 }
]
}
])

The following example calculates the standard deviation of each quiz:

db.quizzes.aggregate([
{ $project: { stdDev: { $stdDevPop: "$scores.score" } } }
])

The operation returns the following results:

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

New in version 5.0.

Create a cakeSales collection that contains cake sales in the states of California (CA) and Washington (WA):

db.cakeSales.insertMany( [
{ _id: 0, type: "chocolate", orderDate: new Date("2020-05-18T14:10:30Z"),
state: "CA", price: 13, quantity: 120 },
{ _id: 1, type: "chocolate", orderDate: new Date("2021-03-20T11:30:05Z"),
state: "WA", price: 14, quantity: 140 },
{ _id: 2, type: "vanilla", orderDate: new Date("2021-01-11T06:31:15Z"),
state: "CA", price: 12, quantity: 145 },
{ _id: 3, type: "vanilla", orderDate: new Date("2020-02-08T13:13:23Z"),
state: "WA", price: 13, quantity: 104 },
{ _id: 4, type: "strawberry", orderDate: new Date("2019-05-18T16:09:01Z"),
state: "CA", price: 41, quantity: 162 },
{ _id: 5, type: "strawberry", orderDate: new Date("2019-01-08T06:12:03Z"),
state: "WA", price: 43, quantity: 134 }
] )

This example uses $stdDevPop in the $setWindowFields stage to output the population standard deviation of the cake sales quantity for each state:

db.cakeSales.aggregate( [
{
$setWindowFields: {
partitionBy: "$state",
sortBy: { orderDate: 1 },
output: {
stdDevPopQuantityForState: {
$stdDevPop: "$quantity",
window: {
documents: [ "unbounded", "current" ]
}
}
}
}
}
] )

In the example:

  • partitionBy: "$state" partitions the documents in the collection by state. There are partitions for CA and WA.

  • sortBy: { orderDate: 1 } sorts the documents in each partition by orderDate in ascending order (1), so the earliest orderDate is first.

  • output sets the stdDevPopQuantityForState field to the quantity population standard deviation value using $stdDevPop that is run in a documents window.

    The window contains documents between an unbounded lower limit and the current document in the output. This means $stdDevPop returns the quantity population standard deviation value for the documents between the beginning of the partition and the current document.

In this example output, the quantity population standard deviation value for CA and WA is shown in the stdDevPopQuantityForState field:

{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
"state" : "CA", "price" : 41, "quantity" : 162, "stdDevPopQuantityForState" : 0 }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
"state" : "CA", "price" : 13, "quantity" : 120, "stdDevPopQuantityForState" : 21 }
{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
"state" : "CA", "price" : 12, "quantity" : 145, "stdDevPopQuantityForState" : 17.249798710580816 }
{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
"state" : "WA", "price" : 43, "quantity" : 134, "stdDevPopQuantityForState" : 0 }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
"state" : "WA", "price" : 13, "quantity" : 104, "stdDevPopQuantityForState" : 15 }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
"state" : "WA", "price" : 14, "quantity" : 140, "stdDevPopQuantityForState" : 15.748015748023622 }
←  $sqrt (aggregation)$stdDevSamp (aggregation) →