$stdDevSamp (aggregation)

Definition

  • $stdDevSamp

New in version 3.2.

Calculates the sample standard deviation of the input values. Use ifthe values encompass a sample of a population of data from whichto generalize about the population. $stdDevSamp ignoresnon-numeric values.

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

$stdDevSamp is available in the in the following stages:

  • $group
  • $project
  • $addFields (Available starting in MongoDB 3.4)
  • $set (Available starting in MongoDB 4.2)
  • $replaceRoot (Available starting in MongoDB 3.4)
  • $replaceWith (Available starting in MongoDB 4.2)
  • $match stage that includes an $expr expressionWhen used in the $group stage, $stdDevSamp has thefollowing syntax and returns the sample standard deviation of thespecified expression for a group of documents that share the samegroup by key:
  1. { $stdDevSamp: <expression> }

When used in the other supported stages,$stdDevSamp returns the sample standard deviation ofthe specified expression or list of expressions for each documentand has one of two syntaxes:

  • $stdDevSamp has one specified expression as its operand:
  1. { $stdDevSamp: <expression> }
  • $stdDevSamp has a list of specified expressions as itsoperand:
  1. { $stdDevSamp: [ <expression1>, <expression2> ... ]  }

The argument for $stdDevSamp can be anyexpression as long as it resolvesto an array. For more information on expressions, seeExpressions.

Behavior

Non-numeric Values

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

Single Value

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

Array Operand

In the $group stage, if the expression resolves to anarray, $stdDevSamp treats the operand as a non-numerical value.

In the other supported stages:

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

Example

A collection users contains documents with the following fields:

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

To calculate the standard deviation of a sample of users, followingaggregation operation first uses the $sample pipeline tosample 100 users, and then uses $stdDevSamp calculates thestandard deviation for the sampled users.

  1. db.users.aggregate(
  2.    [
  3.       { $sample: { size: 100 } },
  4.       { $group: { _id: null, ageStdDev: { $stdDevSamp: "$age" } } }
  5.    ]
  6. )

The operation returns a result like the following:

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