The $maxN accumulator collects the N largest values in each $group bucket—ideal for top-3 scores, highest prices, or peak metrics without a separate $sort stage.
01
N max per group
Array of highest values.
02
input + n
Two required properties.
03
No $sort
Compares across the group.
04
vs $max
Many peaks vs one peak.
05
Nulls filtered
Skips null and missing.
06
vs $topN
Max values vs ranked docs.
Fundamentals
Definition and Usage
$maxN is a MongoDB accumulator used in the $group stage. For each group, it evaluates an input expression on every document, keeps the N largest results, and returns them as an array (typically highest first).
💡
Beginner tip
Think of $max as “give me the single highest score” and $maxN as “give me the top three scores.” Unlike $firstN, $maxN ignores null and missing values automatically.
Use $maxN for leaderboards and top-N reports. When you need guaranteed tie-breaking order or full documents at each rank, prefer $topN with an explicit sortBy.
Foundation
📝 Syntax
As a $group accumulator, $maxN requires input and n:
Use tuple input: ["$score", "$playerId"] to attach context to each top value
Combine $max + $maxN when dashboards need peak and top-N together
Put $match before $group to shrink groups and avoid memory pressure
Use $topN when tie order must follow explicit sortBy rules
Test with groups that have fewer than n valid values to confirm array length
❌ Don’t
Confuse $maxN with $max (array vs single value)
Expect null scores to appear in the result—they are filtered out
Assume output order on tied equal values—use $topN for strict ordering
Compare mixed BSON types without understanding type ordering rules
Deploy on MongoDB versions before 5.2 without a fallback pipeline
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $maxN
Use these points when building top-N max reports inside $group.
5
Core concepts
📈01
Top N values
Largest per group.
Basics
📄02
input + n
Two required keys.
Syntax
📊03
No $sort
Full group compare.
Pattern
👤04
Nulls out
Filtered automatically.
Behavior
🏆05
vs $topN
Max vs ranked docs.
Choose
❓ Frequently Asked Questions
$maxN returns an array of the N largest input values from each $group bucket. It compares values across all documents in the group and keeps the top N—no $sort stage required.
Inside $group: { topThree: { $maxN: { input: "$score", n: 3 } } }. Both input and n are required. It also works as an aggregation expression and window operator.
$max returns a single highest value. $maxN returns an array of up to N highest values. Use $max for the peak alone; use $maxN for a top-N leaderboard of scores or prices.
$maxN finds the N maximum values by comparison without requiring sortBy. $topN ranks inside $group with sortBy and returns the top N documents. Use $topN when you need a guaranteed sort order on ties.
No. Unlike $firstN and $lastN, $maxN filters out null and missing values. If only three documents have scores and n is 4, you get an array of three elements.
$maxN returns all available non-null values—never more than exist. A group with two numeric scores and n: 3 yields an array of two items.
Did you know?
$maxN and $minN were added in MongoDB 5.2 alongside $firstN, $lastN, $topN, and $bottomN—replacing fragile sort-and-slice recipes for top-N numeric reports. See the official $maxN docs.
