$unset (aggregation)

Definition

• $unset

New in version 4.2.

Removes/excludes fields from documents.

Syntax

The $unset stage has the following syntax:

• To remove a single field, the $unset takes a string thatspecifies the field to remove:

{ $unset: "<field>" }

• To remove multiple fields, the $unset takes an array offields to remove.

{ $unset: [ "<field1>", "<field2>", ... ] }

Considerations

$unset and $project

The $unset is an alias for the $projectstage that removes/excludes fields:

{ $project: { "<field1>": 0, "<field2>": 0, ... } }

Embedded Fields

To remove/exclude a field or fields within an embedded document, youcan use the dot notation, as in:

{ $unset: "<field.nestedfield>" }

or

{ $unset: [ "<field1.nestedfield>", ...] }

Examples

Create a sample books collection with the following documents:

db.books.insertMany([
   { "_id" : 1, title: "Antelope Antics", isbn: "0001122223334", author: { last:"An", first: "Auntie" }, copies: [ { warehouse: "A", qty: 5 }, { warehouse: "B", qty: 15 } ] },
   { "_id" : 2, title: "Bees Babble", isbn: "999999999333", author: { last:"Bumble", first: "Bee" }, copies: [ { warehouse: "A", qty: 2 }, { warehouse: "B", qty: 5 } ] }
])

Remove a Single Field

The following example removes the top-level field copies:

db.books.aggregate([ { $unset: "copies" } ])

Alternatively, you can also use the following syntax:

db.books.aggregate([ { $unset: [ "copies" ] } ])

Either operation returns the following documents:

{ "_id" : 1, "title" : "Antelope Antics", "isbn" : "0001122223334", "author" : { "last" : "An", "first" : "Auntie" } }
{ "_id" : 2, "title" : "Bees Babble", "isbn" : "999999999333", "author" : { "last" : "Bumble", "first" : "Bee" } }

Remove Top-Level Fields

The following example removes the top-level fields isbn andcopies:

db.books.aggregate([
   { $unset: [ "isbn", "copies" ] }
])

The $unset operation outputs the following documents:

{ "_id" : 1, "title" : "Antelope Antics", "author" : { "last" : "An", "first" : "Auntie" } }
{ "_id" : 2, "title" : "Bees Babble", "author" : { "last" : "Bumble", "first" : "Bee" } }

Remove Embedded Fields

The following example removes the top-level field isbn, theembedded field first (from the name document) and the embedded fieldwarehouse (from the elements in the copies array):

db.books.aggregate([
   { $unset: [ "isbn", "author.first", "copies.warehouse" ] }
])

The $unset operation outputs the following documents:

{ "_id" : 1, "title" : "Antelope Antics", "author" : { "last" : "An" }, "copies" : [ { "qty" : 5 }, { "qty" : 15 } ] }
{ "_id" : 2, "title" : "Bees Babble", "author" : { "last" : "Bumble" }, "copies" : [ { "qty" : 2 }, { "qty" : 5 } ] }