Using Push & Pull Operators in MongoDB
The $push and $pull operators are a part of array operators designed to modify arrays in MongoDB documents. In this tutorial, I’ll show you how the push and pull operators work and how to use them with additional modifiers and conditions.
(This article is part of our MongoDB Guide. Use the right-hand menu to navigate.)
Push and Pull are the two operations used to add and remove elements from arrays in MongoDB documents. Pushing and pulling elements are done using the MongoDB $push and $pull operators, respectively:
{ $push: { <field1>: <value1>, ... } }
{ $pull: { <field1>: <value|condition>, ... } }
Let’s look at each in more detail, including how they work and how you can use them.
You can see the $push operator takes two arguments:
If the array field is not present in the document, the $push operator will create a new array field. However, if the specified field is not an array, MongoDB will return an error.
The functionality of the $push operator can be further extended using the following modifiers.
The $push operation is carried out in the following order, regardless of the order in which the modifiers are defined:
Next, we will look at how we can use MongoDB $push operations to manipulate documents. I’ll show a few examples, so jump to the one you need:
For the base data set for these examples, I’ll use the “vehicledetails” collection.
db.vehicledetails.find().pretty()
Result:
Let us see how we can append a single value to an array when an array field is present, and it's not present. In all examples, the "_id" field is used to indicate which document the array should be added.
Example: No Array Field
A new array field will be created with the field name specified in the $push operator.
db.vehicledetails.update({"_id": ObjectId("5fbc52f05f9a62418038240d")}, {$push: {"vehicle_colours": "red"}})
Result:
Example: When the array Field is present
The new item will be appended at the end of the array.
db.vehicledetails.update({"_id": ObjectId("5fbc52f05f9a62418038240d")}, {$push: {"vehicle_colours": "green"}})
Result:
If we try to use the $push operator for a non-array field, it will result in an error. The following code returns an error as we are trying to append a value to the non-array field “make”.
db.vehicledetails.update({"_id": ObjectId("5fbc52f05f9a62418038240d")}, {$push: {"make": "green"}})
Result:
You can append multiple values to an array with or without $each modifier.
Example: Multiple Values without $each modifier
If the $each modifier is not present, MongoDB will append all the values as a single value to the specified array field.
db.vehicledetails.update({"_id": ObjectId("5fbc52f55f9a62418038240e")}, {$push: {"vehicle_colours": }})
Result:
Here, you can see "blue", "red", and "yellow" are elements of a newly created array. But that array is just one element of the "vehical_colours" array.
Example: Multiple Values with $each modifier
When a $push operation is defined with the $each modifier, each element in the $push operation will be added to the array as individual items.
db.vehicledetails.update({"_id": ObjectId("5fbc52f55f9a62418038240e")}, {$push: {"vehicle_colours": { $each :}}})
Result:
Here, “vehicle_colours” has three elements after $push operation.
In this section, we will demonstrate how to use the $sort and $slice modifiers using the following document in the “vehicledetails” collection.
Let us add the color "silver" to the "vehicle_colours" array field and sort the contents alphabetically (ascending order).
db.vehicledetails.update({"_id": ObjectId("5fbc52fb5f9a62418038240f")}, {$push: {"vehicle_colours": { $each :, $sort: 1}}})
Result:
The above output shows us that the new colors were added, and the array has been sorted alphabetically. In the following example, we will add the color "dark blue" to the array field while sorting alphabetically and using the $slice modifier to limit the array to 5 elements.
db.vehicledetails.update({"_id": ObjectId("5fbc52fb5f9a62418038240f")}, {$push: {"vehicle_colours": { $each :, $sort: 1, $slice: 5}}})
Result:
The $position modifier is used to specify the location in the array where the new item should be added. This will override the default behavior of appending the items to the end of the array.
In the following example, we will add the color "white" to the beginning of the array field "vehicle_colours". In the "$position" modifier, zero (0) is used to indicate the first position (index 0) of the array.
db.vehicledetails.update({"_id": ObjectId("5fbc52fb5f9a62418038240f")}, {$push: {"vehicle_colours": { $each :, $position: 0}}})
Result:
The $pull operator is used to remove all the instances of a value or values from a MongoDB document that matches a specified condition. If an array contains embedded or nested documents, the specified $pull operator condition will be applied to each array element as if each array element were a document in a collection.
When the specified value to be removed is an array, the $pull operator only removes the elements in the array that matches the exact value specified, including the order in which the elements are defined. If the specified value to remove is a document, the $pull operator will remove elements that match the fields and values specified. In this instance order of fields is discarded.
Now I’ll walk you through a few examples of the $pull operator. Jump to the ones you need:
In these examples, we’ll use the following data set to demonstrate:
Here, we will remove the single value “2018” from the “model_year” array field. The “_id” field is used to indicate the document on which the $pull operation should occur.
db.vehicledetails.update({"_id": ObjectId("5fbc52fb5f9a62418038240f")}, {$pull: {"model_year": 2018}})
Result:
In this example, we will be using the “vehicledetails" collection to remove the colors "blue" and "green" from the "vehicle_colours" array field and remove the model year 2020 from the "model_year" array field.
db.vehicledetails.update({}, {$pull: {"vehicle_colours": { $in: }, "model_year": 2020}},{multi: true})
Result:
Using the collection “student_grades”, let us create a condition to remove all grades that are less than or equal to 50 from the following document.
Unmodified Document:
Modified Document:
db.student_grades.update({"_id" : ObjectId("5fbed0faa94306028d2d7520")}, {$pull: {"grades": {$lte: 50}}})
Result:
The specified condition ({$lte: 50}) removed any item that is less than or equal to 50 in the “grades” array field.
In this example, we will use the “student_grades” collection to remove all the values that are less than or equal to 50 in the “grades” array field in all the documents in the collection.
Unmodified Collection:
Modified Collection:
db.student_grades.update({}, {$pull: {"grades": {$lte: 50}}},{multi: true})
Result:
The above output demonstrates to us that any value that is less than or equal to 50 has been removed from the “grades” array field in all documents in the “student_grades” collection.
That concludes this tutorial.