The $unset stage removes fields from pipeline documents—strip secrets, drop temporary helpers, and trim nested paths while keeping everything else on the document.
01
Remove fields
Array syntax.
02
Dot notation
Nested paths.
03
vs $set
Opposite.
04
vs $project
Drop vs shape.
05
Temp fields
After $set.
06
API cleanup
Safe output.
Fundamentals
Definition and Usage
$unset is an aggregation stage that deletes specified fields from each document in the pipeline stream. Unlike $project, which defines the full output shape, $unset is subtractive—you name what to remove and keep the rest.
💡
Beginner tip
$set = add or overwrite a field. $unset = delete a field. $project: { password: 0 } also hides fields—but $unset reads clearly when removing several known fields by name.
Common uses: remove password hashes before API responses, drop internal _internalId fields, delete temporary sort keys added mid-pipeline, and strip nested paths like metadata.debug.
Foundation
📝 Syntax
$unset takes an array of field name strings to remove:
mongosh
{
$unset: [
<field1>,
<field2>,
...
]
}
// field names are plain strings — use quotes
// dot notation for nested: "address.zipCode"
Syntax Rules
Array of strings — each entry is a field path to remove: [ "password", "ssn" ].
Single field — use a one-element array: { $unset: [ "temp" ] }.
Nested paths — dot notation removes one nested key: "profile.internalNote".
Non-destructive to collection — only affects pipeline documents, not stored data (unless using $out / $merge).
Missing fields — unsetting a field that does not exist is safe—no error.
MongoDB 4.2+ — introduced alongside $set as a readable field-transform stage.
$unset subtracts fields from pipeline documents: list paths in an array, use dot notation for nested keys, and strip secrets or temporary helpers before results reach the client.
For strict allow-list APIs, combine with $project. Next: $unwind to expand array fields into separate documents.
Unset passwords, tokens, and internal IDs in every public-facing pipeline
Remove temporary $set fields after sorting or filtering on them
Batch multiple removals in one $unset array
Use dot notation to drop nested debug or audit paths only
Place $unset late in the pipeline—just before client output
❌ Don’t
Assume $unset deletes data from the collection permanently
Expose fields you forgot to list in $unset—review API pipelines carefully
Use $unset when you only need two fields—$project inclusion may be clearer
Unset _id if downstream stages still need it—unset last or use $project
Chain ten single-field unset stages when one array works
Summary
Key Takeaways
Knowledge Unlocked
Five things to remember about $unset
Use these points when cleaning pipeline document shape.
5
Core concepts
🗑️01
Remove fields
Array syntax.
Basics
🔗02
Dot paths
Nested keys.
Nested
🔄03
vs $set
Opposite.
Pair
🛡️04
Secrets
Strip early.
Security
⚡05
Temp fields
Unset last.
Pattern
❓ Frequently Asked Questions
$unset removes one or more fields from every document passing through the aggregation pipeline. All other fields stay intact. Use it to strip passwords, internal IDs, temporary computed values, or nested paths before returning results to clients.
{ $unset: [ "field1", "field2" ] } — an array of field name strings. For nested paths use dot notation: "address.zipCode". A single field can be passed as a one-element array: [ "password" ].
$unset removes specific named fields; everything else remains. $project reshapes output—you include fields to keep or exclude with 0. Use $unset when dropping a few known fields; use $project when building a slim allow-list for API responses.
Yes. $set adds or overwrites fields; $unset removes them. Common pattern: $set to compute a helper field, use it in $sort or $match, then $unset to drop it before the client sees the document.
No. Like all aggregation stages, $unset only affects documents in the pipeline stream. Original collection data is unchanged unless you write results back with $out or $merge.
Nothing harmful—MongoDB simply omits a field that is not there. The stage succeeds and the document passes through with other fields unchanged.
Did you know?
MongoDB added $set and $unset together in version 4.2—mirroring the update operators of the same names so pipeline field edits feel familiar. The aggregation $unset stage always takes an array of field paths, even when removing just one field. See the official $unset docs.
