MongoDB $stdDevPop Accumulator

What You’ll Learn

The $stdDevPop accumulator measures population standard deviation in each $group bucket—how far numeric values typically spread from their average. Use it when the grouped data represents the complete population you care about.

Definition and Usage

$stdDevPop is a MongoDB accumulator used in the $group stage. For each group, it evaluates a numeric expression on every document and returns the population standard deviation—a measure of how much values vary from their mean.

Use $stdDevPop when your group contains all data you want to describe (every student in a class, every sale in a store for the month). When values are only a sample meant to represent a larger population, use $stdDevSamp instead.

📝 Syntax

$stdDevPop takes one expression inside $group:

{
  $group: {
    _id: <expression>,
    <outputField>: { $stdDevPop: <expression> }
  }
}

Syntax Rules

• Stage — primary use as accumulator in $group (also $bucket, windows).
• Expression — field path like "$score" or a numeric formula.
• Output — a decimal/double standard deviation value, or null if no numeric inputs exist.
• Population formula — divides variance by N (count of numeric values), not N−1.
• Non-numeric — null, missing, strings, booleans, and objects are ignored.
• Single value — one numeric document in a group returns 0.

db.users.aggregate([
  {
    $group: {
      _id: "$quiz",
      stdDev: { $stdDevPop: "$score" }
    }
  }
]);

Examples Gallery

Quiz scores from the MongoDB docs—calculate spread per quiz, combine with $avg, and format readable output.

db.users.insertMany([
  { _id: 1, name: "dave123", quiz: 1, score: 85 },
  { _id: 2, name: "dave2",   quiz: 1, score: 90 },
  { _id: 3, name: "ahn",     quiz: 1, score: 71 },
  { _id: 4, name: "li",      quiz: 2, score: 96 },
  { _id: 5, name: "annT",    quiz: 2, score: 77 },
  { _id: 6, name: "ty",      quiz: 2, score: 82 }
]);

db.users.aggregate([
  {
    $group: {
      _id: "$quiz",
      stdDev: { $stdDevPop: "$score" }
    }
  },
  { $sort: { _id: 1 } }
]);

/* Result:
[
  { _id: 1, stdDev: 8.04155872120988 },
  { _id: 2, stdDev: 8.04155872120988 }
]
*/

Quiz 1 → stdDev ≈ 8.04
Quiz 2 → stdDev ≈ 8.04

db.users.aggregate([
  {
    $group: {
      _id: "$quiz",
      avgScore: { $avg: "$score" },
      stdDev:   { $stdDevPop: "$score" },
      count:    { $sum: 1 }
    }
  },
  { $sort: { _id: 1 } }
]);

/* Quiz 1:
   avgScore ≈ 82, stdDev ≈ 8.04, count: 3
   Quiz 2:
   avgScore ≈ 85, stdDev ≈ 8.04, count: 3 */
*/

avgScore: 82
stdDev:   8.04
count:    3

db.users.aggregate([
  {
    $group: {
      _id: null,
      stdDev: { $stdDevPop: "$score" },
      avgScore: { $avg: "$score" }
    }
  }
]);

/* All six scores: 85, 90, 71, 96, 77, 82
   avg ≈ 83.5, stdDev ≈ 8.28 (population, N=6) */
*/

{ _id: null, stdDev: ~8.28, avgScore: ~83.5 }

db.users.aggregate([
  {
    $group: {
      _id: "$quiz",
      stdDev: { $stdDevPop: "$score" }
    }
  },
  {
    $project: {
      _id: 1,
      stdDev: { $round: ["$stdDev", 2] }
    }
  },
  { $sort: { _id: 1 } }
]);

/* Quiz 1 → { _id: 1, stdDev: 8.04 }
   Quiz 2 → { _id: 2, stdDev: 8.04 } */
*/

stdDev: 8.04 (was 8.04155872120988)

📝 Notes

• $stdDevPop uses the population formula (divide variance by N)—not the sample formula (N−1).
• Non-numeric values are ignored—same behavior as $avg and $sum.
• A group with one numeric value returns 0 standard deviation.
• In $group, an expression that resolves to an array is treated as non-numeric.
• Result type is typically decimal/double—use $round for display.
• Previous topic: $push. Next: $stdDevSamp.

💡 Best Practices