The $avg accumulator computes the arithmetic mean of numeric values while MongoDB groups documents. It is one of the most common tools for dashboards, grades, and KPI reports.
01
Mean per group
Sum ÷ count of numeric values.
02
$group syntax
Accumulator with field or expression.
03
Overall average
Use _id: null for one global mean.
04
Per category
Average salary by department, etc.
05
Null handling
Missing values skipped automatically.
06
vs $sum
Totals vs averages in reports.
Fundamentals
Definition and Usage
$avg is a MongoDB accumulator used in the $group stage. For each group, it evaluates an expression on every document, keeps only numeric values, adds them up, and divides by how many numeric values were counted.
💡
Beginner tip
Scores 85, 75, and 90 average to (85 + 75 + 90) / 3 = 83.33.... MongoDB performs that math for you inside $group—no manual $sum and $count required unless you need both numbers separately.
Use $avg for exam scores, order amounts, response times, ratings, and any metric where the typical value matters more than the total. Filter with $match first to average only relevant documents.
_id: null means “one group containing every document.” The old tutorial example with scores 85, 75, 90 (average 83.33) uses the same pattern with three documents.
📈 Practical Patterns
Break averages down by category, filter first, and format output.
$avg is the go-to MongoDB accumulator for arithmetic means: overall KPIs with _id: null, breakdowns by department or product line, and filtered reports after $match.
Remember it skips non-numeric values, pair it with counts when context matters, and round only at the end. For totals instead of means, use $sum; for spread, explore $stdDevPop and $stdDevSamp.
Place $match before $group to average the right subset
Include document count ($sum: 1) alongside averages in reports
Use $round or $trunc in $project for UI-friendly numbers
Validate that score/amount fields are stored as numbers, not strings
Index fields used in $match before heavy grouping
❌ Don’t
Expect string numbers like "85" to be averaged (they are ignored)
Assume null scores count as zero—they are excluded from the mean
Use $avg when you need a total—use $sum instead
Compare averages across groups with very different counts without noting sample size
Forget that _id: null still outputs _id: null in the result document
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $avg
Use these points whenever you compute means in aggregation pipelines.
5
Core concepts
💲01
Arithmetic mean
Sum ÷ numeric count.
Basics
📦02
$group
Accumulator context.
Syntax
🎯03
_id: null
Global average.
Pattern
⚠04
Skips null
Non-numbers ignored.
Gotcha
📐05
$round
Format for display.
Tip
❓ Frequently Asked Questions
$avg calculates the arithmetic mean of numeric values in each $group bucket. It adds the numbers and divides by the count of numeric inputs, ignoring non-numeric values.
Inside the $group stage: { avgScore: { $avg: "$score" } }. You can also use the $avg expression operator on arrays in $project and $addFields, but this tutorial focuses on the $group accumulator.
Grouping with _id: null puts all documents into one bucket, so $avg returns a single overall average for the entire filtered collection.
Null and missing values are ignored—they do not count toward the sum or the divisor. If no numeric values exist in a group, $avg returns null.
$sum totals numeric values. $avg divides that total by the number of numeric values counted. Use $avg for means (average salary); use $sum for totals (total revenue).
Yes. Pass any numeric expression: { $avg: { $add: ["$base", "$bonus"] } } averages base plus bonus per document in the group.
Did you know?
You can replicate $avg manually with $sum and $sum: 1 plus a $project division stage—but $avg is clearer and handles ignored non-numeric values for you. See the official $avg aggregation docs.
