$pull
On this page
$pull
The
$pull
operator removes from an existing array all instances of a value or values that match a specified condition.
Compatibility
You can use $pull
for deployments hosted in the following
environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Syntax
The $pull
operator has the following form:
{ $pull: { <field1>: <value|condition>, <field2>: <value|condition>, ... } }
To specify a <field>
in an embedded document or in an array, use
dot notation.
Behavior
In MongoDB 4.4 and earlier, update operators process document fields in lexicographic order. See Update Operators Behavior for details.
If you specify a <condition>
and the array elements are embedded
documents, $pull
operator applies the <condition>
as if each
array element were a document in a collection. See
Remove All Items That Match a Specified $pull
Condition With bulkWrite()
for an example.
If the specified <value>
to remove is an array, $pull
removes only the elements in the array that match the specified
<value>
exactly, including order.
If the specified <value>
to remove is a document, $pull
removes only the elements in the array that have the exact same fields
and values. The ordering of the fields can differ.
Examples
Remove All Items That Equal a Specified Value
Given the following document in the stores
collection:
{ _id: 1, fruits: [ "apples", "pears", "oranges", "grapes", "bananas" ], vegetables: [ "carrots", "celery", "squash", "carrots" ] } { _id: 2, fruits: [ "plums", "kiwis", "oranges", "bananas", "apples" ], vegetables: [ "broccoli", "zucchini", "carrots", "onions" ] }
The following operation updates all documents in the collection to
remove "apples"
and "oranges"
from the array fruits
and
remove "carrots"
from the array vegetables
:
db.stores.update( { }, { $pull: { fruits: { $in: [ "apples", "oranges" ] }, vegetables: "carrots" } }, { multi: true } )
After the operation, the fruits
array no longer contains any
"apples"
or "oranges"
values, and the vegetables
array no
longer contains any "carrots"
values:
{ "_id" : 1, "fruits" : [ "pears", "grapes", "bananas" ], "vegetables" : [ "celery", "squash" ] } { "_id" : 2, "fruits" : [ "plums", "kiwis", "bananas" ], "vegetables" : [ "broccoli", "zucchini", "onions" ] }
Remove All Items That Match a Specified $pull
Condition
Given the following document in the profiles
collection:
{ _id: 1, votes: [ 3, 5, 6, 7, 7, 8 ] }
The following operation will remove all items from the votes
array
that are greater than or equal to ($gte
) 6
:
db.profiles.update( { _id: 1 }, { $pull: { votes: { $gte: 6 } } } )
After the update operation, the document only has values less than 6:
{ _id: 1, votes: [ 3, 5 ] }
Remove All Items That Match a Specified $pull
Condition With bulkWrite()
The following db.collection.bulkWrite()
operation:
Creates the
profilesBulkWrite
collection.Removes all items from the
votes
array that are greater than or equal to ($gte
)6
.Removes all items from the
votes
array that are less than or equal to ($lte
)3
.
try { db.profilesBulkWrite.bulkWrite( [ { insertOne: { "document": { _id: 1, votes: [ 3, 5, 6, 7, 7, 8 ] } } }, { updateOne: { "filter": { _id: 1 }, "update": { $pull: { votes: { $gte: 6 } } } } }, { updateOne: { "filter": {_id: 1}, "update": { $pull: { votes: { $lte: 3 } } } } } ] ); } catch (e) { print(e); }
Note
bulkWrite()
The db.collection.bulkWrite()
method executes multiple
write operations listed in an array. In this example, the
db.collection.bulkWrite()
performs multiple operations
on the profiles
collection.
After the db.collection.bulkWrite()
operation,
you can confirm the document only has values less than
6 and greater than 3 using the following
operation:
db.profilesBulkWrite.find()
The operation returns the following:
[ { _id: 1, votes: [ 5 ] } ]
Remove Items from an Array of Documents
A survey
collection contains the following documents:
{ _id: 1, results: [ { item: "A", score: 5 }, { item: "B", score: 8, comment: "Strongly agree" } ] } { _id: 2, results: [ { item: "C", score: 8, comment: "Strongly agree" }, { item: "B", score: 4 } ] }
The following operation will remove from the results
array all
elements that contain both a score
field equal to 8
and an
item
field equal to "B"
:
db.survey.update( { }, { $pull: { results: { score: 8 , item: "B" } } }, { multi: true } )
The $pull
expression applies the condition to each element of
the results
array as though it were a top-level document.
After the operation, the results
array contains no documents that
contain both a score
field equal to 8
and an item
field
equal to "B"
.
{ "_id" : 1, "results" : [ { "item" : "A", "score" : 5 } ] } { "_id" : 2, "results" : [ { "item" : "C", "score" : 8, "comment" : "Strongly agree" }, { "item" : "B", "score" : 4 } ] }
Because $pull
operator applies its query to each element as
though it were a top-level object, the expression did not require the
use of $elemMatch
to specify the condition of a score
field equal to 8
and item
field equal to "B"
. In fact, the
following operation will not pull any element from the original
collection.
db.survey.update( { }, { $pull: { results: { $elemMatch: { score: 8 , item: "B" } } } }, { multi: true } )
However, if the survey
collection contained the following
documents, where the results
array contains embedded documents that
also contain arrays:
{ _id: 1, results: [ { item: "A", score: 5, answers: [ { q: 1, a: 4 }, { q: 2, a: 6 } ] }, { item: "B", score: 8, answers: [ { q: 1, a: 8 }, { q: 2, a: 9 } ] } ] } { _id: 2, results: [ { item: "C", score: 8, answers: [ { q: 1, a: 8 }, { q: 2, a: 7 } ] }, { item: "B", score: 4, answers: [ { q: 1, a: 0 }, { q: 2, a: 8 } ] } ] }
Then you can specify multiple conditions on the elements of the
answers
array with $elemMatch
:
db.survey.update( { }, { $pull: { results: { answers: { $elemMatch: { q: 2, a: { $gte: 8 } } } } } }, { multi: true } )
The operation removed from the results
array those embedded
documents with an answers
field that contained at least one element
with q
equal to 2
and a
greater than or equal to 8
:
{ "_id" : 1, "results" : [ { "item" : "A", "score" : 5, "answers" : [ { "q" : 1, "a" : 4 }, { "q" : 2, "a" : 6 } ] } ] } { "_id" : 2, "results" : [ { "item" : "C", "score" : 8, "answers" : [ { "q" : 1, "a" : 8 }, { "q" : 2, "a" : 7 } ] } ] }