- Reference >
- Operators >
- Update Operators >
- Array Update Operators >
- $pull
$pull¶
- $pull¶
The $pull operator removes from an existing array all instances of a value or values that match a specified query.
{ $pull: { <arrayField>: <value|query> } }
If the array elements are embedded documents, $pull operator applies its specified query to each element as though it were a top-level object. See Remove Items from an Array of Documents for an example.
Examples¶
Remove All Items That Equals a Specified Value¶
Given the following documents in the cpuinfo collection:
{ _id: 1, flags: [ "vme", "de", "msr", "tsc", "pse", "msr" ] }
{ _id: 2, flags: [ "msr", "pse", "tsc" ] }
The following operation removes the value "msr" from the flags array:
db.cpuinfo.update(
{ flags: "msr" },
{ $pull: { flags: "msr" } },
{ multi: true }
)
After the operation, the documents no longer contain any "msr" values in the flags array:
{ _id: 1, flags: [ "vme", "de", "tsc", "pse" ] }
{ _id: 2, flags: [ "pse", "tsc" ] }
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 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 a score field equal to 8 and 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 contains score field equal to 8 and 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 } ] }
]
}