Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions,
see Getting Started with Amazon Web Services in China
(PDF).
$stdDevPop
New from version 8.0.1.
The $stdDevPop operator in Amazon DocumentDB calculates the population standard deviation of numeric values. As an accumulator, it computes the population standard deviation across documents within a group in the $group stage of an aggregation pipeline. As an expression, it calculates the population standard deviation of an array of numbers. The population standard deviation uses N as the divisor (not N-1). Non-numeric values are ignored. If there are no numeric values, it returns null. If there is only one numeric value, it returns 0.
Parameters
Example (MongoDB Shell)
The following example shows how to use the $stdDevPop operator to calculate the population standard deviation of scores per subject.
Create sample documents
db.scores.insertMany([
{ subject: "math", score: 60 },
{ subject: "math", score: 75 },
{ subject: "math", score: 85 },
{ subject: "math", score: 92 },
{ subject: "math", score: 78 },
{ subject: "science", score: 55 },
{ subject: "science", score: 70 },
{ subject: "science", score: 82 },
{ subject: "science", score: 91 },
{ subject: "science", score: 67 }
]);
Query example
db.scores.aggregate([
{ $group: {
_id: "$subject",
stdDev: { $stdDevPop: "$score" }
}}
]);
Output
[
{ "_id": "math", "stdDev": 10.75174404457249 },
{ "_id": "science", "stdDev": 12.441864811996632 }
]
Expression usage example (MongoDB Shell)
The $stdDevPop operator can also be used as an expression within a $project stage to compute the population standard deviation of an array field.
Create sample documents
db.experiments.insertMany([
{ _id: 1, measurements: [10, 12, 14, 16, 18] },
{ _id: 2, measurements: [5, 5, 5, 5, 5] },
{ _id: 3, measurements: [2, 4, 6, 8, 10] }
]);
Query example
db.experiments.aggregate([
{ $project: {
stdDev: { $stdDevPop: "$measurements" }
}}
]);
Output
[
{ "_id": 1, "stdDev": 2.8284271247461903 },
{ "_id": 2, "stdDev": 0 },
{ "_id": 3, "stdDev": 2.8284271247461903 }
]
Window operator usage example (MongoDB Shell)
New from version 8.0.2.
The $stdDevPop operator can also be used as a window operator in the $setWindowFields stage. In this context, it returns the population standard deviation of the specified expression for the documents in each window. You specify the operator under the output field, and optionally define the window boundaries with a window document.
Create sample documents
db.sensorData.insertMany([
{ _id: 1, sensor: "A", time: 1, reading: 4 },
{ _id: 2, sensor: "A", time: 2, reading: 10 },
{ _id: 3, sensor: "A", time: 3, reading: 10 },
{ _id: 4, sensor: "B", time: 1, reading: 10 },
{ _id: 5, sensor: "B", time: 2, reading: 20 }
]);
Query example
The following example partitions the documents by sensor, sorts each partition by time, and returns the running population standard deviation of reading from the start of the partition through the current document.
db.sensorData.aggregate([
{
$setWindowFields: {
partitionBy: "$sensor",
sortBy: { time: 1 },
output: {
runningStdDev: {
$stdDevPop: "$reading",
window: { documents: ["unbounded", "current"] }
}
}
}
}
]);
Output
[
{ "_id": 1, "sensor": "A", "time": 1, "reading": 4, "runningStdDev": 0 },
{ "_id": 2, "sensor": "A", "time": 2, "reading": 10, "runningStdDev": 3 },
{ "_id": 3, "sensor": "A", "time": 3, "reading": 10, "runningStdDev": 2.8284271247461903 },
{ "_id": 4, "sensor": "B", "time": 1, "reading": 10, "runningStdDev": 0 },
{ "_id": 5, "sensor": "B", "time": 2, "reading": 20, "runningStdDev": 5 }
]
Each document is augmented with runningStdDev, the population standard deviation of reading within its partition up to and including the current document. When the window contains a single value, $stdDevPop returns 0.
Code examples
To view a code example for using the $stdDevPop operator, choose the tab for the language that you want to use. The following examples show accumulator usage (in $group), expression usage (in $project), and window operator usage (in $setWindowFields):
- Node.js
-
const { MongoClient } = require('mongodb');
async function example() {
const uri = 'mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false';
const client = new MongoClient(uri);
try {
await client.connect();
const db = client.db('test');
// Accumulator usage: stdDevPop across grouped documents
const scores = db.collection('scores');
await scores.insertMany([
{ subject: "math", score: 60 },
{ subject: "math", score: 75 },
{ subject: "math", score: 85 },
{ subject: "math", score: 92 },
{ subject: "math", score: 78 },
{ subject: "science", score: 55 },
{ subject: "science", score: 70 },
{ subject: "science", score: 82 },
{ subject: "science", score: 91 },
{ subject: "science", score: 67 }
]);
const accumulatorResult = await scores.aggregate([
{ $group: {
_id: "$subject",
stdDev: { $stdDevPop: "$score" }
}}
]).toArray();
console.log('Accumulator result:', accumulatorResult);
// Expression usage: stdDevPop of an array field
const experiments = db.collection('experiments');
await experiments.insertMany([
{ _id: 1, measurements: [10, 12, 14, 16, 18] },
{ _id: 2, measurements: [5, 5, 5, 5, 5] },
{ _id: 3, measurements: [2, 4, 6, 8, 10] }
]);
const expressionResult = await experiments.aggregate([
{ $project: {
stdDev: { $stdDevPop: "$measurements" }
}}
]).toArray();
console.log('Expression result:', expressionResult);
// Window operator usage: running stdDevPop within each partition
const sensorData = db.collection('sensorData');
await sensorData.insertMany([
{ _id: 1, sensor: "A", time: 1, reading: 4 },
{ _id: 2, sensor: "A", time: 2, reading: 10 },
{ _id: 3, sensor: "A", time: 3, reading: 10 },
{ _id: 4, sensor: "B", time: 1, reading: 10 },
{ _id: 5, sensor: "B", time: 2, reading: 20 }
]);
const windowResult = await sensorData.aggregate([
{
$setWindowFields: {
partitionBy: "$sensor",
sortBy: { time: 1 },
output: {
runningStdDev: {
$stdDevPop: "$reading",
window: { documents: ["unbounded", "current"] }
}
}
}
}
]).toArray();
console.log('Window result:', windowResult);
} finally {
await client.close();
}
}
example();
- Python
-
from pymongo import MongoClient
def example():
client = MongoClient('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
try:
db = client['test']
# Accumulator usage: stdDevPop across grouped documents
scores = db['scores']
scores.insert_many([
{ 'subject': 'math', 'score': 60 },
{ 'subject': 'math', 'score': 75 },
{ 'subject': 'math', 'score': 85 },
{ 'subject': 'math', 'score': 92 },
{ 'subject': 'math', 'score': 78 },
{ 'subject': 'science', 'score': 55 },
{ 'subject': 'science', 'score': 70 },
{ 'subject': 'science', 'score': 82 },
{ 'subject': 'science', 'score': 91 },
{ 'subject': 'science', 'score': 67 }
])
accumulator_result = list(scores.aggregate([
{ '$group': {
'_id': '$subject',
'stdDev': { '$stdDevPop': '$score' }
}}
]))
print('Accumulator result:', accumulator_result)
# Expression usage: stdDevPop of an array field
experiments = db['experiments']
experiments.insert_many([
{ '_id': 1, 'measurements': [10, 12, 14, 16, 18] },
{ '_id': 2, 'measurements': [5, 5, 5, 5, 5] },
{ '_id': 3, 'measurements': [2, 4, 6, 8, 10] }
])
expression_result = list(experiments.aggregate([
{ '$project': {
'stdDev': { '$stdDevPop': '$measurements' }
}}
]))
print('Expression result:', expression_result)
# Window operator usage: running stdDevPop within each partition
sensor_data = db['sensorData']
sensor_data.insert_many([
{ '_id': 1, 'sensor': 'A', 'time': 1, 'reading': 4 },
{ '_id': 2, 'sensor': 'A', 'time': 2, 'reading': 10 },
{ '_id': 3, 'sensor': 'A', 'time': 3, 'reading': 10 },
{ '_id': 4, 'sensor': 'B', 'time': 1, 'reading': 10 },
{ '_id': 5, 'sensor': 'B', 'time': 2, 'reading': 20 }
])
window_result = list(sensor_data.aggregate([
{
'$setWindowFields': {
'partitionBy': '$sensor',
'sortBy': { 'time': 1 },
'output': {
'runningStdDev': {
'$stdDevPop': '$reading',
'window': { 'documents': ['unbounded', 'current'] }
}
}
}
}
]))
print('Window result:', window_result)
finally:
client.close()
example()