Docs Home → Develop Applications → MongoDB Manual

# $stdDevSamp (aggregation)

On this page

## Definition

*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)`$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)

## Syntax

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

## Behavior

### Non-numeric Values

`$stdDevSamp`

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

returns `null`

.

### Single Value

If the sample consists of a single numeric value, `$stdDevSamp`

returns `null`

.

### Array Operand

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.

### Window Values

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.

## Examples

### Use in `$group`

Stage

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 }

### Use in `$setWindowFields`

Stage

*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 }