The $top accumulator picks the single highest-ranked document in each $group bucket using a sortBy specification—ideal for “best score,” “latest order,” or “highest price” reports.
Full record at top of sort.
Defines what “top” means.
$$ROOT or selected fields.
Value only vs whole document.
One record vs N records.
Part of $top/$bottom family.
$top is a MongoDB accumulator used in the $group stage. It sorts documents within each group according to sortBy, then returns the document at the top of that ordering—the first document in the sorted list.
With sortBy: { score: -1 }, descending order puts the highest score at the top—so $top returns the student with the best score in each class. Use date: -1 when “top” should mean the most recent record.
Choose $top when you need identifying fields (name, id, date) from the winning record. Use $max when you only need the numeric maximum. Need multiple top-ranked rows? Use $topN.
$top requires an object with output and sortBy:
{
$group: {
_id: <expression>,
<field>: {
$top: {
output: <expression> | { <field>: <expression>, ... },
sortBy: { <field>: <1 | -1>, ... }
}
}
}
}output — what to return: "$$ROOT" for the full document, or a projection object.sortBy — required; same format as $sort (1 = ascending, -1 = descending).$topN, result is a single object per group, not an array.db.scores.aggregate([
{
$group: {
_id: "$class",
topScorer: {
$top: {
output: { name: "$student", score: "$score" },
sortBy: { score: -1 }
}
}
}
}
]);| Question | Answer |
|---|---|
| Stage | $group accumulator |
| Required keys | output, sortBy |
| Returns | One document (or projected object) per group |
| Highest score pattern | sortBy: { score: -1 } |
| Full document | output: "$$ROOT" |
| MongoDB version | 5.2+ |
sortBy: { score: -1 }Descending → max at top
sortBy: { date: -1 }Most recent at top
output: "$$ROOT"Entire source document
sortBy: {
score: -1,
student: 1
}Stable ordering
The $top object has two required properties:
output RequiredExpression or document defining what the accumulator returns. Use "$$ROOT" for the full input document, or build a sub-object with field projections.
output: "$$ROOT"
output: { id: "$_id", score: "$score" }sortBy RequiredSort specification applied within each group before picking the top document. Mirrors $sort syntax with 1 (asc) and -1 (desc).
sortBy: { score: -1 }
sortBy: { date: -1, amount: -1 }_id Group keyStandard $group bucket key—e.g. "$class" for per-class top scorers.
_id: "$department"empty group Edge caseIf no documents fall in a group, that group is not emitted. Pipelines with only empty buckets return an empty result set.
$match before $groupStudent scores by class—find the top scorer per section, return full documents, and compare with $max.
Sample scores and the core $top grouping pattern.
db.scores.insertMany([
{ student: "Alice", class: "10A", score: 85 },
{ student: "Bob", class: "10A", score: 72 },
{ student: "Charlie", class: "10A", score: 91 },
{ student: "Diana", class: "10B", score: 68 },
{ student: "Eve", class: "10B", score: 88 }
]);Class 10A top scorer is Charlie (91); class 10B top scorer is Eve (88)—clear targets for verifying $top output.
db.scores.aggregate([
{
$group: {
_id: "$class",
topScorer: {
$top: {
output: { name: "$student", score: "$score" },
sortBy: { score: -1 }
}
}
}
},
{ $sort: { _id: 1 } }
]);
/* Result:
[
{ _id: "10A", topScorer: { name: "Charlie", score: 91 } },
{ _id: "10B", topScorer: { name: "Eve", score: 88 } }
]
*/Within each class group, MongoDB sorts by descending score and returns the top document’s projected fields.
Return full documents, compare accumulators, and handle ties.
db.scores.aggregate([
{
$group: {
_id: "$class",
topRecord: {
$top: {
output: "$$ROOT",
sortBy: { score: -1 }
}
}
}
}
]);
// topRecord contains student, class, score, _id fields$$ROOT refers to the current document in the group during accumulation—useful when downstream stages need every field.
db.scores.aggregate([
{
$group: {
_id: "$class",
maxScore: { $max: "$score" },
topStudent: {
$top: {
output: { name: "$student", score: "$score" },
sortBy: { score: -1 }
}
}
}
}
]);
/* 10A:
maxScore: 91
topStudent: { name: "Charlie", score: 91 }
— same number, but $top also gives you the name */
*/Use both in the same $group when dashboards show the peak value and the record that achieved it.
When two students share the highest score, add a secondary key so ranking is predictable:
db.scores.aggregate([
{
$group: {
_id: "$class",
topScorer: {
$top: {
output: { name: "$student", score: "$score" },
sortBy: { score: -1, student: 1 }
}
}
}
}
]);
// If Charlie and Chris both score 91, student: 1
// puts Charlie before Chris — Charlie wins the tieAlways add tie-breakers (name, timestamp, _id) when business rules require deterministic winners.
$top Works$group assigns each document to a group via _id.
sortBy ranks documents inside each bucket independently.
The first document in that sort order becomes the accumulator result.
The output expression shapes what fields appear in the final object.
$top requires MongoDB 5.2+—verify server version before deploying.sortBy is mandatory—there is no default sort order.$topN for many).sortBy keys.$sort + $group + $first patterns (less efficient).$top answers “which single record is at the high end of my ranking?” inside each group. Define sortBy carefully, project with output, and add tie-breakers when duplicates matter.
Pair with $max for the numeric peak alone, or move to $topN when you need several top-ranked documents per bucket.
sortBy explicitly—match your business definition of “top”student, _id) to break ties$$ROOT when downstream stages need the full document$match before $group to shrink working sets$top with $topN (one doc vs array)$max to return student names—it only returns the maximum valuesortBy fields$topUse these points when ranking documents inside $group.
Top of sort per group.
BasicsRequired ranking spec.
SyntaxDoc vs scalar value.
CompareReturn full record.
PatternCheck server version.
Version$top and $bottom were added together in MongoDB 5.2 to replace fragile $sort + $group + $first recipes for ranked group results. Before 5.2, developers often sorted the entire collection globally and hoped group order stayed correct—$top ranks inside each bucket independently. See the official $top docs.
Pick the single top record with $top, then learn $topN for multiple ranked results.
5 people found this page helpful