$firstN (First N Accumulator)
Last updated: 2026-10-09
$firstN (First N Accumulator)
$firstN is an accumulator returning an array of a field's values from the first N documents of a group (in input order), available since MongoDB 5.2. Related to $first as $topN is to $top, but it follows input order rather than a sort rule. n can be constant or expression.
| Category | Accumulators |
|---|---|
| MongoDB Version | 5.2+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $group: { _id: <key>, firstN: { $firstN: { input: <expression>, n: <number> } } } }Returns：Array of expression values from the first N documents of the group
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $firstN: prices of the earliest 3 records per item
db.sales.aggregate([
{ $sort: { date: 1 } },
{ $group: { _id: '$item', first3: { $firstN: { input: '$price', n: 3 } } } }
])Output：
{ "_id": "Pen", "first3": [20, 25, 30] }📌 Notes
- Requires MongoDB 5.2 or later
- Order depends on input, so $sort first for meaning
- n accepts an expression for dynamic counts
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QWhat is the difference between $firstN and $topN?
A$firstN takes the first N in input order; $topN takes the top N by a sortBy rule.
QDo I need to sort first?
AOrder follows input; $sort by time first to grab the earliest N.
QWhat if n exceeds the group size?
AIt returns every value in the group.
