The $firstN accumulator collects the first N input values from each $group bucket—ideal for the first three orders per customer, earliest events, or top-N lists when you define order with $sort.
01
N values per group
Array of leading records.
02
input + n
Two required properties.
03
Needs $sort
Order before $group matters.
04
vs $first
Many values vs one value.
05
vs $topN
Pre-sorted vs in-group rank.
06
Array operator too
Slice arrays in $project.
Fundamentals
Definition and Usage
$firstN is a MongoDB accumulator used in the $group stage. For each group, it evaluates an input expression on the first n documents (in pipeline order) and returns those values as an array.
💡
Beginner tip
$firstN does not sort documents. It simply takes the first N docs that reach each group. Add $sort before $group when you need earliest dates, highest scores first, or any predictable ordering.
Use $firstN when the stream is already ordered. If you need MongoDB to rank inside the group, consider $topN instead. For a single leading value, use $first.
Foundation
📝 Syntax
As a $group accumulator, $firstN requires input and n:
$firstN extends $first to collect several leading values per group. Pair it with $sort, set input and n, and you get clean top-N or earliest-N reports without manual $push + $slice workarounds.
Need only one value? Use $first. Need ranking inside the group? Try $topN. Next up: $last for the trailing document value.
Add $sort before $group whenever order defines “first”
Include tie-break sort keys (_id, name) for stable arrays
Use tuple input: ["$player", "$score"] for compact leaderboard rows
Test groups smaller than n to confirm array length behavior
Use the array-operator form to slice existing array fields in $addFields
❌ Don’t
Confuse $firstN with $first (array vs single value)
Skip $sort and expect consistent top-N or earliest-N results
Use $firstN when $topN in-group ranking is clearer
Assume null/missing values are skipped—they are included in the array
Deploy on MongoDB versions before 5.2 without a fallback pipeline
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $firstN
Use these points when building first-N lists inside $group.
5
Core concepts
📦01
Array of N
Leading values per group.
Basics
📄02
input + n
Two required keys.
Syntax
📅03
$sort first
Define what first means.
Pattern
👤04
vs $first
List vs single value.
Compare
📈05
vs $topN
Pre-sort vs in-group rank.
Choose
❓ Frequently Asked Questions
$firstN returns an array of the first N input values from each $group bucket—based on the order documents arrive at $group. Use it for the first three orders per customer, opening prices, or earliest N events when you control order with $sort.
Inside $group: { firstThree: { $firstN: { input: "$score", n: 3 } } }. Both input and n are required. It also works as an array operator in $project and $addFields to slice the first N elements from an array field.
Yes, whenever order matters. $firstN collects the first N documents as they enter each group—it does not sort for you. Add $sort before $group so first means earliest, cheapest, or highest per your rules.
$first returns one value from the first document. $firstN returns an array of up to N values from the first N documents. Use $first for a single field; use $firstN for a list of leading records.
$firstN assumes documents are already ordered (usually via $sort). $topN sorts inside $group with sortBy and picks the top N. Use $firstN when you sorted upstream; use $topN when ranking happens in the accumulator.
$firstN returns all available elements—never more than exist in the group. A group with two documents and n: 3 yields an array of two items.
Did you know?
$firstN doubles as an array operator—you can slice the first three elements from an array field in $addFields without grouping at all. As a group accumulator, it replaced older $push + $slice recipes for top-N lists. See the official $firstN docs.
