$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:
$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 numeric 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-numeric 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, returnsnull
.If the window contains
Infinity
values, returnsnull
.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 bystate
. There are partitions forCA
andWA
.sortBy: { orderDate: 1 }
sorts the documents in each partition byorderDate
in ascending order (1
), so the earliestorderDate
is first.
output
sets thestdDevSampQuantityForState
field to the sample standard deviation of thequantity
values using$stdDevSamp
that is run in a documents window.The window contains documents between an
unbounded
lower limit and thecurrent
document in the output. This means$stdDevSamp
returns the sample standard deviation of thequantity
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 }