$pull

  • $pull
  • The $pull operator removes from an existing array allinstances of a value or values that match a specified condition.

The $pull operator has the form:

  1. { $pull: { <field1>: <value|condition>, <field2>: <value|condition>, ... } }

To specify a <field> in an embedded document or in an array, usedot notation.

Behavior

If you specify a <condition> and the array elements are embeddeddocuments, $pull operator applies the <condition> as if eacharray element were a document in a collection. SeeRemove Items from an Array of Documents for an example.

If the specified <value> to remove is an array, $pullremoves only the elements in the array that match the specified<value> exactly, including order.

If the specified <value> to remove is a document, $pullremoves only the elements in the array that have the exact same fieldsand 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:

  1. {
  2.    _id: 1,
  3.    fruits: [ "apples", "pears", "oranges", "grapes", "bananas" ],
  4.    vegetables: [ "carrots", "celery", "squash", "carrots" ]
  5. }
  6. {
  7.    _id: 2,
  8.    fruits: [ "plums", "kiwis", "oranges", "bananas", "apples" ],
  9.    vegetables: [ "broccoli", "zucchini", "carrots", "onions" ]
  10. }

The following operation updates all documents in the collection toremove "apples" and "oranges" from the array fruits andremove "carrots" from the array vegetables:

  1. db.stores.update(
  2.     { },
  3.     { $pull: { fruits: { $in: [ "apples", "oranges" ] }, vegetables: "carrots" } },
  4.     { multi: true }
  5. )

After the operation, the fruits array no longer contains any"apples" or "oranges" values, and the vegetables array nolonger contains any "carrots" values:

  1. {
  2.   "_id" : 1,
  3.   "fruits" : [ "pears", "grapes", "bananas" ],
  4.   "vegetables" : [ "celery", "squash" ]
  5. }
  6. {
  7.   "_id" : 2,
  8.   "fruits" : [ "plums", "kiwis", "bananas" ],
  9.   "vegetables" : [ "broccoli", "zucchini", "onions" ]
  10. }

Remove All Items That Match a Specified $pull Condition

Given the following document in the profiles collection:

  1. { _id: 1, votes: [ 3, 5, 6, 7, 7, 8 ] }

The following operation will remove all items from the votes arraythat are greater than or equal to ($gte) 6:

  1. db.profiles.update( { _id: 1 }, { $pull: { votes: { $gte: 6 } } } )

After the update operation, the document only has values less than 6:

  1. { _id: 1, votes: [  3,  5 ] }

Remove Items from an Array of Documents

A survey collection contains the following documents:

  1. {
  2.    _id: 1,
  3.    results: [
  4.       { item: "A", score: 5 },
  5.       { item: "B", score: 8, comment: "Strongly agree" }
  6.    ]
  7. }
  8. {
  9.    _id: 2,
  10.    results: [
  11.       { item: "C", score: 8, comment: "Strongly agree" },
  12.       { item: "B", score: 4 }
  13.    ]
  14. }

The following operation will remove from the results array allelements that contain both a score field equal to 8 and anitem field equal to "B":

  1. db.survey.update(
  2.   { },
  3.   { $pull: { results: { score: 8 , item: "B" } } },
  4.   { multi: true }
  5. )

The $pull expression applies the condition to each element ofthe results array as though it were a top-level document.

After the operation, the results array contains no documents thatcontain both a score field equal to 8 and an item fieldequal to "B".

  1. {
  2.    "_id" : 1,
  3.    "results" : [ { "item" : "A", "score" : 5 } ]
  4. }
  5. {
  6.   "_id" : 2,
  7.   "results" : [
  8.       { "item" : "C", "score" : 8, "comment" : "Strongly agree" },
  9.       { "item" : "B", "score" : 4 }
  10.    ]
  11. }

Because $pull operator applies its query to each element asthough it were a top-level object, the expression did not require theuse of $elemMatch to specify the condition of a scorefield equal to 8 and item field equal to "B". In fact, thefollowing operation will not pull any element from the originalcollection.

  1. db.survey.update(
  2.   { },
  3.   { $pull: { results: { $elemMatch: { score: 8 , item: "B" } } } },
  4.   { multi: true }
  5. )

However, if the survey collection contained the followingdocuments, where the results array contains embedded documents thatalso contain arrays:

  1. {
  2.    _id: 1,
  3.    results: [
  4.       { item: "A", score: 5, answers: [ { q: 1, a: 4 }, { q: 2, a: 6 } ] },
  5.       { item: "B", score: 8, answers: [ { q: 1, a: 8 }, { q: 2, a: 9 } ] }
  6.    ]
  7. }
  8. {
  9.    _id: 2,
  10.    results: [
  11.       { item: "C", score: 8, answers: [ { q: 1, a: 8 }, { q: 2, a: 7 } ] },
  12.       { item: "B", score: 4, answers: [ { q: 1, a: 0 }, { q: 2, a: 8 } ] }
  13.    ]
  14. }

Then you can specify multiple conditions on the elements of theanswers array with $elemMatch:

  1. db.survey.update(
  2.   { },
  3.   { $pull: { results: { answers: { $elemMatch: { q: 2, a: { $gte: 8 } } } } } },
  4.   { multi: true }
  5. )

The operation removed from the results array those embeddeddocuments with an answers field that contained at least one elementwith q equal to 2 and a greater than or equal to 8:

  1. {
  2.    "_id" : 1,
  3.    "results" : [
  4.       { "item" : "A", "score" : 5, "answers" : [ { "q" : 1, "a" : 4 }, { "q" : 2, "a" : 6 } ] }
  5.    ]
  6. }
  7. {
  8.    "_id" : 2,
  9.    "results" : [
  10.       { "item" : "C", "score" : 8, "answers" : [ { "q" : 1, "a" : 8 }, { "q" : 2, "a" : 7 } ] }
  11.    ]
  12. }

See also

db.collection.update(),db.collection.findAndModify()