Docs Menu
Docs Home
/
MongoDB Manual
/ / /

$stdDevSamp (aggregation)

On this page

  • Definition
  • Syntax
  • Behavior
  • Examples
$stdDevSamp

Changed in version 5.0.

Calculates the sample standard deviation of the input values. Use if the values encompass a sample of a population of data from which to generalize about the population. $stdDevSamp ignores non-numeric values.

If the values represent the entire population of data or you do not wish to generalize about a larger population, use $stdDevPop instead.

$stdDevSamp is available in these stages:

  • $addFields (Available starting in MongoDB 3.4)

  • $group

  • $match stage that includes an $expr expression

  • $project

  • $replaceRoot (Available starting in MongoDB 3.4)

  • $replaceWith (Available starting in MongoDB 4.2)

  • $set (Available starting in MongoDB 4.2)

  • $setWindowFields (Available starting in MongoDB 5.0)

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

{ $stdDevSamp: <expression> }

When used in other supported stages, $stdDevSamp has one of two syntaxes:

  • $stdDevSamp has one specified expression as its operand:

    { $stdDevSamp: <expression> }
  • $stdDevSamp has a list of specified expressions as its operand:

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

The argument for $stdDevSamp can be any expression as long as it resolves to an array.

For more information on expressions, see Expression Operators.

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

If the sample consists of a single numeric value, $stdDevSamp returns null.

In the $group and $setWindowFields stages, if the expression resolves to an array, $stdDevSamp treats the operand as a non-numerical value.

In the other supported stages:

  • With a single expression as its operand, if the expression resolves to an array, $stdDevSamp 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, $stdDevSamp 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 users contains documents with the following fields:

{_id: 0, username: "user0", age: 20}
{_id: 1, username: "user1", age: 42}
{_id: 2, username: "user2", age: 28}
...

To calculate the standard deviation of a sample of users, following aggregation operation first uses the $sample pipeline to sample 100 users, and then uses $stdDevSamp calculates the standard deviation for the sampled users.

db.users.aggregate(
[
{ $sample: { size: 100 } },
{ $group: { _id: null, ageStdDev: { $stdDevSamp: "$age" } } }
]
)

The operation returns a result like the following:

{ "_id" : null, "ageStdDev" : 7.811258386185771 }

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 $stdDevSamp in the $setWindowFields stage to output the sample standard deviation of the quantity values of the cake sales for each state:

db.cakeSales.aggregate( [
{
$setWindowFields: {
partitionBy: "$state",
sortBy: { orderDate: 1 },
output: {
stdDevSampQuantityForState: {
$stdDevSamp: "$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 stdDevSampQuantityForState field to the sample standard deviation of the quantity values using $stdDevSamp 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 $stdDevSamp returns the sample standard deviation of the quantity values for the documents between the beginning of the partition and the current document.

In this output, the sample standard deviation quantity value for CA and WA is shown in the stdDevSampQuantityForState field:

{ "_id" : 4, "type" : "strawberry", "orderDate" : ISODate("2019-05-18T16:09:01Z"),
"state" : "CA", "price" : 41, "quantity" : 162, "stdDevSampQuantityForState" : null }
{ "_id" : 0, "type" : "chocolate", "orderDate" : ISODate("2020-05-18T14:10:30Z"),
"state" : "CA", "price" : 13, "quantity" : 120, "stdDevSampQuantityForState" : 29.698484809834994 }
{ "_id" : 2, "type" : "vanilla", "orderDate" : ISODate("2021-01-11T06:31:15Z"),
"state" : "CA", "price" : 12, "quantity" : 145, "stdDevSampQuantityForState" : 21.1266025033211 }
{ "_id" : 5, "type" : "strawberry", "orderDate" : ISODate("2019-01-08T06:12:03Z"),
"state" : "WA", "price" : 43, "quantity" : 134, "stdDevSampQuantityForState" : null }
{ "_id" : 3, "type" : "vanilla", "orderDate" : ISODate("2020-02-08T13:13:23Z"),
"state" : "WA", "price" : 13, "quantity" : 104, "stdDevSampQuantityForState" : 21.213203435596427 }
{ "_id" : 1, "type" : "chocolate", "orderDate" : ISODate("2021-03-20T11:30:05Z"),
"state" : "WA", "price" : 14, "quantity" : 140, "stdDevSampQuantityForState" : 19.28730152198591 }

Back

$stdDevPop (aggregation)