The $push accumulator builds an array of every value while MongoDB groups documents—keeping duplicates and preserving processing order. It is ideal for event logs, score histories, and full lists per category.
01
Append all values
Duplicates included.
02
$group syntax
Accumulator with field or expression.
03
vs $addToSet
Full list vs distinct set.
04
Order matters
$sort before $group.
05
Sub-documents
Push object shapes per row.
06
$unwind pattern
Scalars from nested arrays.
Fundamentals
Definition and Usage
$push is a MongoDB accumulator used inside the $group stage. For each group, it evaluates an expression on every input document and appends the result to an output array—without removing duplicates.
💡
Beginner tip
Think of $push as “collect everything I saw, in order” and $addToSet as “collect each different value once.” Both return arrays; only $push keeps repeats.
Typical uses include building order histories per customer, listing every score in a class, or gathering audit events per user. Pair with $sort before $group when chronological order matters, and with $size afterward to count entries.
Use $push when every occurrence counts (transactions, events). Use $addToSet when you only need the distinct set (unique cities visited at least once).
Example 5 — Push sub-documents per order
Build an array of line-item objects for each customer:
$push is the standard MongoDB accumulator when you need every value per group: full city visit lists, order line items, score histories, or audit trails. Sort before grouping when order matters, and use $size to count entries.
When duplicates should be removed, switch to $addToSet. For custom fold logic, see $accumulator.
Use $push when every occurrence or sequence matters
Add $sort before $group for chronological or ranked arrays
Push object literals to capture multiple fields per document in one array entry
Combine with $size for entry counts per group
$unwind nested arrays when you need individual elements pushed
❌ Don’t
Use $push when you only need distinct values ($addToSet instead)
Assume output arrays are deduplicated automatically
Push unbounded arrays on huge groups without testing memory and document size limits
Mix up aggregation $push with update $push modifier syntax
Forget that pipeline order before $group defines append order
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $push
Use these points whenever you build full-value aggregation arrays.
5
Core concepts
📦01
Append all
Duplicates kept.
Basics
📄02
$group only
Accumulator context.
Syntax
🔄03
vs $addToSet
All vs distinct.
Compare
📅04
$sort first
Control order.
Pattern
📝05
Sub-docs
Object per push.
Advanced
❓ Frequently Asked Questions
$push appends the result of an expression to an array for each document in a $group bucket. Every value is kept—including duplicates—and the array grows as MongoDB processes documents in the group.
Inside the $group stage as an accumulator: { allCities: { $push: "$city" } }. It is not a query filter operator—it runs while grouping documents into buckets.
$push keeps every value including repeats. $addToSet only adds a value if it is not already in the array. Use $push for full histories and ordered lists; use $addToSet for distinct sets.
Yes. Values are appended in the order MongoDB processes documents within the group. Use $sort before $group when you need a specific ordering (e.g. chronological events).
$push adds the entire array as one element unless you $unwind the field first. To collect individual tags from nested arrays, $unwind before $group, then $push each scalar.
Yes. Use an object expression: { $push: { score: "$score", name: "$name" } } to build an array of embedded documents per group—useful for activity feeds and audit trails.
Did you know?
MongoDB also has an update operator named $push (with modifiers like $each and $slice) for adding items to an array on a single document. The aggregation accumulator you learned here runs inside $group across many documents. Same name, different pipeline stage. See the official $push aggregation docs.
