> 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, csharp, nodejs
-->

# $replaceRoot (aggregation stage)

## Definition

Replaces the input document with the specified document. The operation replaces all existing fields in the input document, including the `_id` field. You can promote an existing embedded document to the top level, or create a new document for promotion (see [example](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#std-label-new-replacement-doc)).

**Note:**

You can also use the [`$replaceWith`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replacewith.md#mongodb-pipeline-pipe.-replaceWith) stage. The [`$replaceWith`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replacewith.md#mongodb-pipeline-pipe.-replaceWith) stage peforms the same action as the [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) stage, but the stages have different forms.

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

```javascript
{ $replaceRoot: { newRoot: <replacementDocument> } }
```

The replacement document can be any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) that resolves to a document. The stage errors and fails if `<replacementDocument>` is not a document. For more information on expressions, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions)

## Behavior

If the `<replacementDocument>` is not a document, [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) errors and fails.

If the `<replacementDocument>` resolves to a missing document (i.e. the document does not exist), [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) errors and fails. For example, create a collection with the following documents:

```javascript
db.collection.insertMany([
   { "_id": 1, "name" : { "first" : "John", "last" : "Backus" } },
   { "_id": 2, "name" : { "first" : "John", "last" : "McCarthy" } },
   { "_id": 3, "name": { "first" : "Grace", "last" : "Hopper" } },
   { "_id": 4, "firstname": "Ole-Johan", "lastname" : "Dahl" },
])

```

Then the following [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) operation fails because one of the documents does not have the `name` field:

```javascript
db.collection.aggregate([
   { $replaceRoot: { newRoot: "$name" } }
])

```

To avoid the error, you can use [`$mergeObjects`](https://www.mongodb.com/docs/manual/reference/expression/mergeobjects.md#mongodb-expression-exp.-mergeObjects) to merge the `name` document into some default document; for example:

```javascript
db.collection.aggregate([
   { $replaceRoot: { newRoot: { $mergeObjects: [ { _id: "$_id", first: "", last: "" }, "$name" ] } } }
])

```

**Output:**

```javascript
[
  { _id: 1, first: 'John', last: 'Backus' },
  { _id: 2, first: 'John', last: 'McCarthy' },
  { _id: 3, first: 'Grace', last: 'Hopper' },
  { _id: 4, first: '', last: '' }
]

```

Alternatively, you can skip the documents that are missing the `name` field by including a [`$match`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/match.md#mongodb-pipeline-pipe.-match) stage to check for existence of the document field before passing documents to the [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) stage:

```javascript
db.collection.aggregate([
   { $match: { name : { $exists: true, $not: { $type: "array" }, $type: "object" } } },
   { $replaceRoot: { newRoot: "$name" } }
])

```

**Output:**

```javascript
[
  { first: 'John', last: 'Backus' },
  { first: 'John', last: 'McCarthy' },
  { first: 'Grace', last: 'Hopper' }
]

```

Or, you can use [`$ifNull`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/ifnull.md#mongodb-expression-exp.-ifNull) expression to specify some other document to be root; for example:

```javascript
db.collection.aggregate([
   { $replaceRoot: { newRoot: { $ifNull: [ "$name", { _id: "$_id", missingName: true} ] } } }
])

```

**Output:**

```javascript
[
  { first: 'John', last: 'Backus' },
  { first: 'John', last: 'McCarthy' },
  { first: 'Grace', last: 'Hopper' },
  { _id: 4, missingName: true }
]

```

## Examples

### MongoDB Shell

### `$replaceRoot` with an Embedded Document Field

A collection named `people` contains the following documents:

```javascript
db.people.insertMany([
   { "_id" : 1, "name" : "Arlene", "age" : 34, "pets" : { "dogs" : 2, "cats" : 1 } },
   { "_id" : 2, "name" : "Sam", "age" : 41, "pets" : { "cats" : 1, "fish" : 3 } },
   { "_id" : 3, "name" : "Maria", "age" : 25 }
])

```

The following operation uses the [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) stage to replace each input document with the result of a [`$mergeObjects`](https://www.mongodb.com/docs/manual/reference/expression/mergeobjects.md#mongodb-expression-exp.-mergeObjects) operation. The [`$mergeObjects`](https://www.mongodb.com/docs/manual/reference/expression/mergeobjects.md#mongodb-expression-exp.-mergeObjects) expression merges the specified default document with the `pets` document.

```javascript
db.people.aggregate( [
   { $replaceRoot: { newRoot: { $mergeObjects:  [ { dogs: 0, cats: 0, birds: 0, fish: 0 }, "$pets" ] } } }
] )

```

**Output:**

```javascript
[
  { dogs: 2, cats: 1, birds: 0, fish: 0 },
  { dogs: 0, cats: 1, birds: 0, fish: 3 },
  { dogs: 0, cats: 0, birds: 0, fish: 0 }
]

```

### `$replaceRoot` with a Document Nested in an Array

A collection named `students` contains the following documents:

```javascript
db.students.insertMany([
   {
      "_id" : 1,
      "grades" : [
         { "test": 1, "grade" : 80, "mean" : 75, "std" : 6 },
         { "test": 2, "grade" : 85, "mean" : 90, "std" : 4 },
         { "test": 3, "grade" : 95, "mean" : 85, "std" : 6 }
      ]
   },
   {
      "_id" : 2,
      "grades" : [
         { "test": 1, "grade" : 90, "mean" : 75, "std" : 6 },
         { "test": 2, "grade" : 87, "mean" : 90, "std" : 3 },
         { "test": 3, "grade" : 91, "mean" : 85, "std" : 4 }
      ]
   }
])

```

The following operation promotes the embedded document(s) with the `grade` field greater than or equal to `90` to the top level:

```javascript
db.students.aggregate( [
   { $unwind: "$grades" },
   { $match: { "grades.grade" : { $gte: 90 } } },
   { $replaceRoot: { newRoot: "$grades" } }
] )

```

**Output:**

```javascript
[
  { test: 3, grade: 95, mean: 85, std: 6 },
  { test: 1, grade: 90, mean: 75, std: 6 },
  { test: 3, grade: 91, mean: 85, std: 4 }
]

```

### `$replaceRoot` with a newly created document

You can also create new documents as part of the `$replaceRoot` stage and use them to replace all the other fields.

A collection named `contacts` contains the following documents:

```javascript
db.contacts.insertMany([
   { "_id" : 1, "first_name" : "Gary", "last_name" : "Sheffield", "city" : "New York" },
   { "_id" : 2, "first_name" : "Nancy", "last_name" : "Walker", "city" : "Anaheim" },
   { "_id" : 3, "first_name" : "Peter", "last_name" : "Sumner", "city" : "Toledo" }
])

```

The following operation creates a new document out of the `first_name` and `last_name` fields.

```javascript
db.contacts.aggregate( [
   {
      $replaceRoot: {
         newRoot: {
            full_name: {
               $concat : [ "$first_name", " ", "$last_name" ]
            }
         }
      }
   }
] )

```

**Output:**

```javascript
[
  { full_name: 'Gary Sheffield' },
  { full_name: 'Nancy Walker' },
  { full_name: 'Peter Sumner' }
]

```

### `$replaceRoot` with a New Document Created from `$$ROOT` and a Default Document

A collection named `contacts` contains the following documents:

```javascript
db.contacts.insertMany( [
   { "_id" : 1, name: "Fred", email: "fred@example.net" },
   { "_id" : 2, name: "Frank N. Stine", cell: "012-345-9999" },
   { "_id" : 3, name: "Gren Dell", home: "987-654-3210", email: "beo@example.net" }
] )

```

The following operation uses [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) with [`$mergeObjects`](https://www.mongodb.com/docs/manual/reference/expression/mergeobjects.md#mongodb-expression-exp.-mergeObjects) to output current documents with default values for missing fields:

```javascript
db.contacts.aggregate( [
   { $replaceRoot:
      { newRoot:
         { $mergeObjects:
             [
                { _id: "", name: "", email: "", cell: "", home: "" },
                "$$ROOT"
             ]
          }
      }
   }
] )

```

**Output:**

```javascript
[
  { _id: 1, name: 'Fred', email: 'fred@example.net', cell: '', home: '' },
  {
    _id: 2,
    name: 'Frank N. Stine',
    email: '',
    cell: '012-345-9999',
    home: ''
  },
  {
    _id: 3,
    name: 'Gren Dell',
    email: 'beo@example.net',
    cell: '',
    home: '987-654-3210'
  }
]

```

## Learn More

To learn more about related pipeline stages, see the [`$replaceRoot`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceroot.md#mongodb-pipeline-pipe.-replaceRoot) guide.