$pull (Remove Matching Elements)
Last updated: 2026-10-09
$pull (Remove Matching Elements)
$pull removes from an array every element that equals a value or satisfies a condition. `{ $pull: { tags: 'spam' } }` removes all 'spam'; `{ $pull: { scores: { $lt: 60 } } }` removes every score below 60. It removes all matches, not just one — the standard tool for cleaning arrays.
| Category | Update Array |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $pull: { <array field>: <value> | <condition> } }⚙️ Parameters
| array field | The array field to clean. |
|---|---|
| value or condition | An equality value or query condition, e.g. 'spam' or { $lt: 60 }. |
Returns：The update result
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $pull: remove all spam tags
db.articles.updateOne(
{ _id: 1 },
{ $pull: { tags: 'spam' } }
)
// Remove scores below 60
db.students.updateOne(
{ _id: 1 },
{ $pull: { scores: { $lt: 60 } } }
)Output：
// All spam tags and all scores below 60 are removed📌 Notes
- Removes every matching element, not just one
- Conditions accept operators ($lt, $in, $gt, etc.)
- For arrays of documents, match on their fields
🏷️ Related Tags
💡 Related Cases
Array and Nested Document Queries
Hands-On: CRUD for a Blog Comment System
Document Update: A Detailed Explanation of `updateOne` and `updateMany`
📚 Related Tutorials
❓ FAQ
QWhat is the difference between $pull and $pop?
A$pull removes by value or condition anywhere; $pop removes only the first or last.
QCan $pull remove by condition?
AYes, conditions support query operators, e.g. { $pull: { scores: { $lt: 60 } } }.
QDoes $pull remove all matches or just one?
AAll matching elements are removed.
