Array Update Operators: $push, $pull, $addToSet

Arrays inside MongoDB documents are common—a product has tags, a user has roles, an order has items. When these arrays need to change (add a tag, remove a role, append an order item), you need array update operators that modify the array in-place rather than replacing the entire document.

MongoDB provides a full set of operators for this purpose: $push adds elements, $pull removes elements by value, $pop removes from ends, and $addToSet adds only if unique. All of these are atomic—the change happens in a single server-side operation.

The $push operator appends one or more elements to an array field. If the field does not exist, $push creates it as a new array containing the pushed element. If the field exists but is not an array, the operation fails.

A single $push with a plain value adds one element. To add multiple elements in one operation, combine $push with the $each modifier. $push does not check for duplicates—use $addToSet if you need uniqueness.

Combining $push with the $sort and $slice modifiers creates a capped sorted array: push new elements, sort the array, then trim it to a maximum length. This pattern is perfect for maintaining a 'top N' list or a 'recent N items' log.

The $slice modifier limits the array to the first N elements after sorting. Use negative values for last N (e.g., $slice: -5 keeps the last 5 after sort). This combination requires $each even if you are pushing a single item.

The $pull operator removes all elements from an array that match a specified value or condition. Unlike $pop (which removes from an end), $pull removes elements by their value anywhere in the array.

You can pass a simple value (for primitive arrays) or a query condition (for arrays of sub-documents). $pull removes all matching elements in one atomic operation—there is no need to know the position of the element.

The $pop operator removes the first or last element of an array without needing to know the value. Use $pop: { field: 1 } to remove the last element, and $pop: { field: -1 } to remove the first element.

$pop is useful for implementing queues and deques: push to the back with $push, pop from the front with $pop: -1. However, for production queue systems, consider dedicated solutions—document-based queues have limitations under high concurrency.

The $addToSet operator adds an element to an array only if it is not already present. If the element already exists, the operation is a no-op—no duplicate is added. This is ideal for maintaining sets of unique values like tags, user roles, or category memberships.

Like $push, $addToSet supports the $each modifier to add multiple unique elements in one operation. If the field does not exist, it creates the array. BSON type and value must match exactly for the duplicate check.

The choice between $push and $addToSet depends on whether order and duplicates are acceptable:

• Use $push when: order matters, duplicates are acceptable (or expected), you need sorted arrays with $sort/$slice, or you are building a log/history where repeated values make sense
• Use $addToSet when: you are managing a set of unique values (roles, permissions, tags, subscriptions) and adding an existing value should be a no-op

Keep in mind that $addToSet must scan the existing array to check for duplicates—for very large arrays (thousands of elements), this can be slow. Consider a separate collection for large unique sets.

When your document has an array of sub-documents and you need to remove a specific sub-document by one of its fields, use $pull with a condition expression. The condition is evaluated against each array element and all matching elements are removed.

For removing multiple specific values at once from a primitive array, $pullAll is a shortcut that accepts an array of values to remove: { $pullAll: { tags: ['oldTag1', 'oldTag2'] } }. It is equivalent to { $pull: { tags: { $in: ['oldTag1', 'oldTag2'] } } }.

Be cautious about unbounded array growth. Arrays that grow without limit (unbounded arrays) cause documents to grow beyond MongoDB's 16 MB limit and degrade performance as the array index size grows.

Strategies for bounded arrays:

• Use $push + $slice: -N to keep only the last N elements (rolling window)
• Set a business rule: maximum 50 items in cart, maximum 100 history entries
• For truly unbounded collections, move to a separate collection with a reference instead of embedding

Social features like 'follow user' and 'unfollow user' map naturally to $addToSet and $pull. When a user follows someone, add the followed user's ID to the follower's following array. When they unfollow, pull it out. The atomic nature of these operators means two simultaneous follow/unfollow actions on the same document will be serialized correctly.

For large social graphs (millions of followers), this embedded array approach hits the 16 MB document limit. At scale, move relationships to a dedicated follows collection with followerId and followeeId fields.

When you need to update a specific element within an array that matched your query, use the positional $ operator. In the update document, $ refers to the first array element that matched the filter condition.

For example, to mark a specific order item as shipped, filter by { 'items.sku': 'A1' } and then update { : { 'items.$.shipped': true } }. The $ acts as a placeholder for the index of the matched array element. If multiple elements match, only the first is updated.

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

In this lesson you learned: $push appends elements to an array and supports $each/$sort/$slice modifiers for maintaining capped sorted arrays like top-N lists, $pull removes all matching elements by value or condition—use $pullAll to remove multiple specific values at once, and $addToSet adds an element only if absent—ideal for maintaining unique sets like user roles, tags, and permissions without application-level duplicate checks. Next up we explore how to safely delete documents with deleteOne and deleteMany.