> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  drivers: shell, nodejs
-->

# $unset (aggregation stage)

## Definition

**Note: Disambiguation**

The following page refers to the aggregation stage [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset). For the update operator [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/update/unset.md#mongodb-update-up.-unset), see [`$unset`.](https://www.mongodb.com/docs/manual/reference/operator/update/unset.md#mongodb-update-up.-unset)

Removes/excludes fields from documents.

## Syntax

The [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) stage has the following syntax:

- To remove a single field, the [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) takes a string that specifies the field to remove:

  ```javascript
  { $unset: "<field>" }
  ```

- To remove multiple fields, the [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) takes an array of fields to remove.

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

## Considerations

### `$unset` and `$project`

The [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) is an alias for the [`$project`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/project.md#mongodb-pipeline-pipe.-project) stage that removes/excludes fields:

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

### Embedded Fields

To remove/exclude a field or fields within an embedded document, you can use the [dot notation](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-dot-notation), as in:

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

or

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

## Examples

### MongoDB Shell

Create a sample `books` collection with the following documents:

```javascript
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`:

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

Alternatively, you can also use the following syntax:

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

Either operation returns the following documents:

```javascript
{ "_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` and `copies`:

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

The [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) operation outputs the following documents:

```javascript
{ "_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`, the embedded field `first` (from the `name` document) and the embedded field `warehouse` (from the elements in the `copies` array):

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

The [`$unset`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset.md#mongodb-pipeline-pipe.-unset) operation outputs the following documents:

```javascript
{ "_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 } ] }
```