I still see teams burn time on array cleanup because they treat arrays like separate tables. A common example: a skills list, feature flags, tags, or permissions that drift out of date. You run a feature sunset, but the "beta" flag still hangs around in half your documents. I have watched engineers read an entire document, remove values in code, then write the full document back—slow, noisy, and easy to race. The $pull operator exists for exactly this scenario. It removes matching values from arrays in place, without shipping the whole array to your app.
You are about to see how I use $pull safely in production, how it behaves with nested data, and how to avoid the usual foot-guns. I will show concrete examples you can copy, explain when to prefer $pull over other update operators, and give you testing strategies that work in 2026-style workflows. By the end, you should feel confident cleaning arrays in MongoDB without extra round trips, without brittle client code, and without surprises.
Why $pull is the right tool for array cleanup
When you mutate arrays, you have three main options: replace the entire array, compute a new array with an update pipeline, or remove elements in place with a targeted operator. $pull is the in-place option. It removes any element that matches a value or a condition. That "condition" part is the key: you can delete complex nested elements without writing client code.
I recommend $pull when all you need is deletion. It keeps the update payload small and keeps the server in control of concurrency. For example, a profile document might have skills, tags, or preferences. If your app deletes one of those values, you should send a direct $pull update, not fetch/modify/save.
Here is the mental model I teach: $pull behaves like a filter. Each array element is checked against your condition; matching elements are removed. No match? Nothing changes. That also means $pull is idempotent. If you run the update twice, the second run does nothing.
Syntax and matching rules you must understand
The core syntax is short, but the matching rules deserve attention:
{ $pull: { : , ... } }
I rely on three rules:
1) Value match: If you pass a literal value, MongoDB removes array elements that equal that value.
2) Document match: If array elements are documents, it removes elements whose fields and values match the document you provide. Field order does not matter.
3) Condition match: If you pass a condition document (like $in, $gte, $regex), each array element is tested as if it were a document.
A practical example: an array of objects [{ name: "alpha", enabled: true }] can be cleaned by $pull: { features: { enabled: false } }. You are not matching the whole object, just the condition.
Important: if no elements match, the update results show modifiedCount or nModified as 0, and MongoDB does not throw an error. In the client, you should treat that as "nothing to remove," not as a failure.
A working baseline example you can run
I like to start with a small collection you can build locally. The examples below use a contributor collection. You can paste them into mongosh and run them as is.
// Seed data
use demo
db.contributor.drop()
db.contributor.insertMany([
{ _id: 1, name: "Alice", skills: ["JavaScript", "Python", "Java"] },
{ _id: 2, name: "Bob", skills: ["JavaScript", "Java", "C++"] },
{ _id: 3, name: "Charlie", skills: ["Python", "Ruby", "JavaScript"] }
])
Remove a specific value from arrays
// Remove "Java" from anyone who has it
const result = db.contributor.updateMany(
{ skills: "Java" },
{ $pull: { skills: "Java" } }
)
printjson(result)
If you query the collection afterward, you will see Java removed wherever it appears, and no other values touched.
Remove multiple values with a condition
// Remove JavaScript and Python wherever they appear
const result = db.contributor.updateMany(
{ skills: { $in: ["JavaScript", "Python"] } },
{ $pull: { skills: { $in: ["JavaScript", "Python"] } } }
)
printjson(result)
I prefer $in inside $pull instead of two separate updates. It is one write and one index scan.
Remove based on a rule
// Remove any skill shorter than 5 characters
const result = db.contributor.updateMany(
{},
{ $pull: { skills: { $regex: /^.{1,4}$/ } } }
)
printjson(result)
Notice how the regex is evaluated against each element in the array. That is the filter mental model in action.
Remove all instances of a value
// Remove all "JavaScript" entries everywhere
const result = db.contributor.updateMany(
{},
{ $pull: { skills: "JavaScript" } }
)
printjson(result)
The update removes every instance of the value across the array, not just the first match.
$pull with nested arrays and embedded documents
Most real schemas contain nested arrays of objects. That is where $pull shines because you can match by subfields. Here is a realistic document shape:
// A more complex collection
use demo
db.account.drop()
db.account.insertMany([
{
_id: 1,
owner: "Maya",
devices: [
{ id: "A1", os: "iOS", active: true },
{ id: "B2", os: "Android", active: false }
],
teams: [
{ name: "alpha", members: ["Maya", "Ravi"] },
{ name: "beta", members: ["Maya", "Lin"] }
]
},
{
_id: 2,
owner: "Ravi",
devices: [
{ id: "C3", os: "Android", active: false }
],
teams: [
{ name: "alpha", members: ["Ravi"] }
]
}
])
Remove inactive device records
const result = db.account.updateMany(
{},
{ $pull: { devices: { active: false } } }
)
printjson(result)
This removes any device object with active: false. The rest of the device object is irrelevant because we are matching a condition, not a full object.
Remove a team by name
const result = db.account.updateMany(
{},
{ $pull: { teams: { name: "beta" } } }
)
printjson(result)
Matching by a single field is cleaner than building the entire object in the update. It also avoids bugs when extra fields are added later.
Remove a member from every team array
Here is where $pull targets nested arrays with dot notation. We want to remove a member name inside teams.members.
const result = db.account.updateMany(
{},
{ $pull: { "teams.$[].members": "Maya" } }
)
printjson(result)
Note the $[] all-positional operator. It says "for every element in teams, apply this pull to its members array." This is one of the most reliable ways to remove an item from nested arrays without writing a loop in client code.
Deeper matching semantics: what actually matches
I have seen bugs caused by assuming $pull does partial matching automatically. It does not. The behavior changes based on the shape of what you pass to $pull.
Literal value match
If you pass a literal value, MongoDB uses equality. For arrays of strings, numbers, or ObjectIds, this is straightforward.
// Remove a specific tag
{ $pull: { tags: "archived" } }
Document match is exact
If array elements are documents and you pass a document, MongoDB matches the entire document. That means extra fields will prevent a match.
// This matches only if the element has exactly { id: "A1", os: "iOS" }
{ $pull: { devices: { id: "A1", os: "iOS" } } }
If the element has { id: "A1", os: "iOS", active: true }, the example above will not match. When I need a partial match, I use a condition document.
Condition match is flexible
Condition documents allow partial matching and operators:
{ $pull: { devices: { id: "A1" } } }
{ $pull: { devices: { active: false } } }
{ $pull: { devices: { os: { $in: ["iOS", "Android"] } } } }
$elemMatch inside $pull
You can also use $elemMatch if you want to express more complex criteria with multiple conditions on an element.
{ $pull: { devices: { $elemMatch: { os: "Android", active: false } } } }
This is handy when I need to be explicit about a compound match and avoid confusion for teammates.
What happens when the field is missing or not an array
If the field does not exist, $pull is a no-op. If the field exists but is not an array, the update does nothing. I still treat this as a data smell. In production, I often add a lightweight schema validator or application-level checks to keep the field shape consistent.
$pull vs update pipelines: when each makes sense
In 2026, update pipelines are the default for complex transforms, but they are not always the right choice. I use this heuristic:
- If you only need to remove elements, prefer $pull.
- If you need to transform elements, use update pipelines ($set, $map, $filter).
- If you need to both remove and transform, weigh readability and testability; pipeline might be clearer.
Here is a quick comparison you can use for team discussions:
Traditional approach
My recommendation
—
—
Read, filter in app, write back
Use $pull
Client filtering
Use $pull
Client mapping
Use pipeline
Multiple writes
Use pipelineI still see people default to update pipelines for simple deletions. It works, but it is more complex and it is easier to break. $pull is short, clear, and less error-prone.
$pull vs $pullAll: know the difference
I reach for $pullAll when I want to remove a list of exact values and nothing else. It is basically a multi-value equality remove, with no conditions.
// Remove a list of exact tags
{ $pullAll: { tags: ["legacy", "beta", "deprecated"] } }
I still prefer $pull with $in because it is more flexible and it reads well, but $pullAll can be slightly simpler when you want exact matches only. The main risk is accidental confusion between $pullAll and $pull with $in. In code reviews, I highlight it explicitly to avoid mistakes.
Performance and concurrency in real systems
Array cleanup sounds trivial until you have 100,000 docs or arrays with thousands of entries. That is where server-side updates matter.
Performance notes I have observed
- Small arrays (0–20 items): updates are typically fast, often in the 1–5ms range in a local environment, and 10–15ms in production with modest load. Your exact numbers depend on indexes and storage.
- Medium arrays (20–200 items): still fine, but you should watch update throughput if you run large batch jobs. I have seen 15–40ms per update in busy clusters.
- Large arrays (200+ items): $pull still works, but you should avoid unbounded bulk updates in peak hours. Consider batch jobs and throttling.
Because $pull runs on the server, you avoid a read-modify-write race. If two clients try to remove values concurrently, both updates remain safe because MongoDB applies them in sequence. In contrast, client-side filtering can accidentally overwrite the other client’s updates.
Indexing considerations
$pull itself does not need a special index, but your query filter does. If you update many docs by skills: "Java", index skills so you are not scanning the entire collection. For multi-tenant data, include the tenant key in the filter so your update does not touch unrelated tenants.
// Helpful index for skills array updates
// This allows the query { skills: "Java" } to use an index
use demo
db.contributor.createIndex({ skills: 1 })
I also recommend creating a compound index when you scope updates by tenant or owner:
// Example: multi-tenant update filter
// { tenantId: 42, skills: "Java" }
db.contributor.createIndex({ tenantId: 1, skills: 1 })
Write concern and durability
When array cleanup matters for correctness, I set an explicit write concern. I usually use majority in production so the removal is durable across replica members. If I am cleaning low-value data, I might use a lower write concern or batch updates.
const result = db.contributor.updateMany(
{ skills: "Java" },
{ $pull: { skills: "Java" } },
{ writeConcern: { w: "majority" } }
)
Common mistakes I see and how to avoid them
If your $pull updates are "not working," the issue is usually one of these:
1) Wrong field path
– If you have nested arrays, use dot notation or positional operators. For example, teams.members is not the same as members.
2) Matching the wrong shape
– If array elements are objects, { $pull: { items: { id: "A1" } } } works, but { $pull: { items: { id: "A1", status: "active" } } } will not match if status is missing or different.
3) Expecting partial object match without a condition
– If you pass an object as a literal value, MongoDB matches the full object. To match only a subset of fields, use a condition object.
4) Confusing $pull with $pop
– $pop removes the first or last element by position. $pull removes elements by match. If you want "remove the oldest entry," you probably want $pop or a pipeline.
5) Forgetting array filters for nested arrays
– For nested arrays, you may need $[] or $[] with arrayFilters. Without it, the update may not target what you think it targets.
Here is a safe pattern for nested arrays where you only want to remove members from a specific team:
const result = db.account.updateMany(
{ "teams.name": "alpha" },
{ $pull: { "teams.$[t].members": "Ravi" } },
{ arrayFilters: [{ "t.name": "alpha" }] }
)
printjson(result)
The arrayFilters clause tells MongoDB exactly which array element to update, and avoids touching other team entries.
Edge cases and data hygiene that matter in production
Here are the cases that have bitten me or teammates in real systems, and how I handle them.
Duplicate entries in arrays
$pull removes all matching instances, not just one. That is usually good, but if duplicates are meaningful, be careful. I often enforce uniqueness at the application layer or with $addToSet for inserts. If you do that, $pull becomes a simple and safe inverse.
Mixed types in arrays
If your array contains both strings and objects, matching can behave in surprising ways. I avoid mixed types unless I have a strong reason. When I inherit mixed-type data, I normalize it first with a pipeline update, then use $pull.
Nulls and empty strings
If you have a lot of empty or null items, $pull is an easy cleanup tool:
{ $pull: { tags: { $in: [null, ""] } } }
But in a schema where null has meaning, do not delete it blindly. I add a comment in migration scripts explaining why I remove nulls so future me does not wonder.
Arrays in arrays
When you have arrays inside arrays, you need positional operators to reach the inner array. This is where $[] or arrayFilters are essential. I treat nested arrays as an anti-pattern unless the data model demands it, because updates get tricky fast.
Regex matching
Regex inside $pull is powerful but can be dangerous. Always anchor your regex when possible, and consider collation rules if case-insensitive matching matters. Unbounded regex on large arrays is one of the fastest ways to create slow updates.
When you should not use $pull
I like $pull, but I avoid it in a few cases:
- You need to reorder the remaining elements. $pull only removes elements; it will not re-sort the array. Use an update pipeline if order matters.
- You need to remove based on computed logic. For example, "remove items whose score is below the median." That is a pipeline job, not $pull.
- You are doing a large batch cleanup with reporting needs. If you need to log each deletion, it is better to fetch the documents, compute diffs, and store audit records explicitly.
If your requirements fall into those buckets, write a pipeline update or a batch job. But for most day-to-day cleanup, $pull is still the simplest and safest route.
Production patterns I recommend in 2026
Tooling has changed, but the core database behavior has not. Here are patterns that work well with modern workflows and AI-assisted development.
Pattern: feature flag cleanup
When a feature flag is retired, you want to remove it everywhere. I prefer to store feature flags as an array of strings because it keeps the schema simple. Then a cleanup is a single update:
// Remove deprecated flag across all tenants
const result = db.accounts.updateMany(
{ flags: "legacy_checkout" },
{ $pull: { flags: "legacy_checkout" } }
)
printjson(result)
Pattern: preference pruning with conditions
Preferences are often stored as objects with key, value, scope. When a scope becomes invalid, remove those entries by condition:
const result = db.userPrefs.updateMany(
{},
{ $pull: { prefs: { scope: "org" } } }
)
printjson(result)
Pattern: audit-safe deletions
If you must keep track of removals, you can combine $pull with a $push to an audit log in the same update. That keeps the change atomic.
const result = db.contributor.updateMany(
{ skills: "Java" },
{
$pull: { skills: "Java" },
$push: { audit: { action: "removed-skill", value: "Java", at: new Date() } }
}
)
printjson(result)
This pattern avoids race conditions and keeps your audit trail consistent with the update.
Pattern: AI-assisted cleanup scripts
In my experience, the best use of AI in 2026 is generating safe cleanup scripts, not executing them blindly. I often ask a model to draft the query and update shape, then I review it and run it with a limit or a dry-run query first. For example:
// Dry run: see who will be affected
const preview = db.contributor.find({ skills: "Java" }, { name: 1, skills: 1 })
preview.forEach(doc => printjson(doc))
Then I apply the update with $pull. This is a good habit when the cleanup has business impact.
Operational playbook: how I run large $pull jobs
When I need to clean arrays across millions of documents, I follow a predictable playbook.
1) Define the exact filter and test on a small sample.
2) Create or verify indexes on the filter fields.
3) Run a dry run query to estimate scope.
4) Batch updates by tenant or by _id range.
5) Monitor write throughput, replication lag, and op counters.
6) Capture metrics (matchedCount, modifiedCount) per batch.
7) Record a rollback plan or snapshot before executing.
If you use a job runner, I suggest using a bulkWrite with limited batch size, plus a backoff strategy when the cluster is under load. In large fleets, I also schedule cleanup tasks in off-peak windows, and I throttle updates to keep replication lag under a few seconds.
Bulk writes: efficient cleanup at scale
When I have to update many different filters, I use bulkWrite. It keeps the wire overhead low and provides per-operation feedback.
const ops = [
{
updateMany: {
filter: { tenantId: 1, tags: "legacy" },
update: { $pull: { tags: "legacy" } }
}
},
{
updateMany: {
filter: { tenantId: 2, tags: "legacy" },
update: { $pull: { tags: "legacy" } }
}
}
]
const result = db.accounts.bulkWrite(ops, { ordered: false })
printjson(result)
I set ordered: false so one failure does not block the rest. I also capture result.getRawResponse() in real scripts to log counts for audits.
$pull in transactions: when I need stronger guarantees
Most updates do not need a transaction, but sometimes I need to coordinate array cleanup with other updates across collections. In those cases, I use a session and a transaction. This is especially useful when a removal must correspond to a state change elsewhere.
const session = db.getMongo().startSession()
try {
session.startTransaction()
db.accounts.updateOne(
{ _id: 123 },
{ $pull: { flags: "legacy_checkout" } },
{ session }
)
db.audit.insertOne(
{ accountId: 123, action: "flagremoved", value: "legacycheckout", at: new Date() },
{ session }
)
session.commitTransaction()
} catch (err) {
session.abortTransaction()
throw err
} finally {
session.endSession()
}
Transactions add overhead, so I use them sparingly. But when you need atomicity across collections, they are worth it.
Testing $pull updates in code
When you test data operations, you want repeatable fixtures and small targeted assertions. Here is a Node.js example using the MongoDB driver and node:test. You can swap it for Jest or Vitest if your stack uses those.
import test from "node:test"
import assert from "node:assert/strict"
import { MongoClient } from "mongodb"
const uri = "mongodb://localhost:27017"
const client = new MongoClient(uri)
await client.connect()
const db = client.db("demo")
const contributor = db.collection("contributor")
await contributor.deleteMany({})
await contributor.insertMany([
{ _id: 1, name: "Alice", skills: ["JavaScript", "Python", "Java"] },
{ _id: 2, name: "Bob", skills: ["JavaScript", "Java", "C++"] }
])
test("$pull removes a specific skill", async () => {
const result = await contributor.updateMany(
{ skills: "Java" },
{ $pull: { skills: "Java" } }
)
assert.equal(result.modifiedCount, 2)
const alice = await contributor.findOne({ _id: 1 })
assert.deepEqual(alice.skills, ["JavaScript", "Python"])
const bob = await contributor.findOne({ _id: 2 })
assert.deepEqual(bob.skills, ["JavaScript", "C++"])
})
test("$pull is idempotent", async () => {
const result = await contributor.updateMany(
{ skills: "Java" },
{ $pull: { skills: "Java" } }
)
assert.equal(result.modifiedCount, 0)
})
Python test example
If you are in a Python stack, I use pytest with a local MongoDB for integration tests. The idea is the same: insert fixtures, run $pull, assert the resulting array.
import pytest
from pymongo import MongoClient
@pytest.fixture()
def contributor():
client = MongoClient("mongodb://localhost:27017")
db = client["demo"]
col = db["contributor"]
col.delete_many({})
col.insert_many([
{"_id": 1, "name": "Alice", "skills": ["JavaScript", "Python", "Java"]},
{"_id": 2, "name": "Bob", "skills": ["JavaScript", "Java", "C++"]},
])
yield col
client.close()
def testpullremoves_skill(contributor):
result = contributor.update_many(
{"skills": "Java"},
{"$pull": {"skills": "Java"}},
)
assert result.modified_count == 2
assert contributor.findone({"id": 1})["skills"] == ["JavaScript", "Python"]
assert contributor.findone({"id": 2})["skills"] == ["JavaScript", "C++"]
In both examples, I assert modifiedCount or modified_count to confirm the update actually changed data. I also add an idempotency test because that is a key property when you run cleanup jobs multiple times.
Practical scenarios and how I solve them
Here are a few situations that come up often, with the pattern I use.
Remove stale permissions from every account
I keep permissions as strings. When a permission is deprecated, I remove it by $pull and log the batch size.
const result = db.accounts.updateMany(
{ permissions: "can_export" },
{ $pull: { permissions: "can_export" } }
)
printjson({ matched: result.matchedCount, modified: result.modifiedCount })
Remove expired tokens stored as objects
Tokens often expire and are stored as array objects. Here is the pattern:
const now = new Date()
const result = db.sessions.updateMany(
{},
{ $pull: { tokens: { expiresAt: { $lte: now } } } }
)
printjson(result)
Remove a specific device for a specific account
This combines a filter and a $pull. This is the pattern I use for one-off cleanups.
db.account.updateOne(
{ _id: 1 },
{ $pull: { devices: { id: "B2" } } }
)
Troubleshooting checklist I actually use
When a $pull update does not do what I expect, I run through this list quickly:
- Check the field path: is it the array you think it is?
- Confirm the element shape: is it a literal value or an object?
- Verify the query filter: are you matching the right documents?
- Run a find projection to inspect the actual array values.
- Try a small $pull in mongosh against one document.
- Confirm no schema drift: is the field sometimes a string instead of an array?
Most issues are one of those, and I can usually fix them in minutes.
Schema design choices that make $pull easy
I always think about cleanup at design time. It saves time later.
- Favor arrays of strings for flags, tags, and permissions. It makes $pull trivial.
- For objects, keep a stable identifier field (id, key, name) so you can match on one field.
- Avoid deeply nested arrays unless they provide a clear benefit.
- Use $addToSet for inserts so you do not end up cleaning duplicates later.
If you inherit a legacy schema, I still design cleanup scripts that normalize the arrays first. That keeps future updates simple.
Alternative approaches and why I still pick $pull
There are a few alternatives to $pull, each with trade-offs.
Client-side filtering
This is the slowest and most error-prone option. I avoid it for anything beyond single-document, low-traffic edits. It is too easy to overwrite concurrent updates.
Update pipeline with $filter
Pipelines are powerful and useful for complex transforms, but for simple removals they are more verbose and harder to review quickly. I use them when I need to transform or reorder elements, not when I just need to delete.
Rebuild arrays offline
Sometimes I rebuild arrays offline when I need audit-friendly logs or cross-document reports. This is rare, but it is the right tool when business rules are complex and I need to record every removal.
Observability and monitoring for cleanup jobs
When I run cleanup jobs, I track three numbers per batch:
- matchedCount: how many docs the filter matched
- modifiedCount: how many docs actually changed
- runtime per batch: a crude latency signal
If matchedCount is high but modifiedCount is low, it usually means my $pull condition is off. If runtime per batch spikes, it is often a sign of poor indexing or a cluster under load.
I also emit a structured log per batch with tenantId, batch size, matchedCount, modifiedCount, and error count. This gives me a clear audit trail without logging entire documents.
A small case study: cleaning nested teams safely
I once inherited a dataset where each account had a teams array, and each team had members. Over time, old members were never removed from teams, even after they left the company. The naive fix was a script that fetched each document, filtered members in code, and replaced the array. That script was slow and stomped on concurrent updates.
The fix was a $pull with arrayFilters:
const result = db.account.updateMany(
{ "teams.name": "alpha" },
{ $pull: { "teams.$[t].members": "FormerUser" } },
{ arrayFilters: [{ "t.name": "alpha" }] }
)
The update ran in minutes rather than hours, did not overwrite other changes, and gave us predictable modifiedCount results for reporting. It was the cleanest refactor I have seen for nested arrays.
Security and safety guardrails
Array cleanup can be dangerous if you aim it at the wrong set of documents. I use the following guardrails:
- Always include a tenant or account filter when data is multi-tenant.
- Use a dry-run find to inspect the affected documents.
- Log the update parameters and counts for auditability.
- Keep a backup or snapshot for risky migrations.
- Run large updates in off-peak windows with throttling.
These steps are boring, but they save you from the worst-case mistake of pulling data you should not remove.
Summary: how I decide to use $pull
If I need to delete elements from arrays, I reach for $pull first. It is simple, server-side, and safe for concurrency. If I need to transform or reorder, I use update pipelines. If I need detailed audit records for each deletion, I use client-side diffing or a dedicated job.
The most important takeaway is this: you do not need to read the document, mutate an array in application code, and write it back. That pattern creates races, adds latency, and multiplies failure points. $pull does the job where the data lives.
If you follow the patterns above, you will have fast, safe, and testable array cleanup in MongoDB. That is exactly what $pull is for, and it is still one of the most useful operators in day-to-day production work.
