Docs Menu

$pull

On this page

  • Behavior
  • Examples
$pull

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

The $pull operator has the form:

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

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

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 Items from an Array of Documents 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.

Starting in MongoDB 5.0, mongod no longer raises an error when you use an update operator like $pull with an empty operand expression ( { } ). An empty update results in no changes and no oplog entry is created (meaning that the operation is a no-op).

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" ]
}

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 ] }

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 } ] }
]
}
Tip
See also:
←  $pop$push →

On this page

Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.