$rename¶

$rename¶

New in version 1.7.2.

Syntax: {$rename: { <old name1>: <new name1>, <old name2>: <new name2>, ... } }

The $rename operator updates the name of a field. The new field name must differ from the existing field name.

Consider the following example:

db.students.update( { _id: 1 }, { $rename: { 'nickname': 'alias', 'cell': 'mobile' } } )

This operation renames the field nickname to alias, and the field cell to mobile.

If the document already has a field with the new field name, the $rename operator removes that field and renames the field with the old field name to the new field name.

The $rename operator will expand arrays and sub-documents to find a match for field names. When renaming a field in a sub-document to another sub-document or to a regular field, the sub-document itself remains.

Consider the following examples involving the sub-document of the following document:

copy

{ "_id": 1,
  "alias": [ "The American Cincinnatus", "The American Fabius" ],
  "mobile": "555-555-5555",
  "nmae": { "first" : "george", "last" : "washington" }
}

To rename a sub-document, call the $rename operator with the name of the sub-document as you would any other field:

copy

db.students.update( { _id: 1 }, { $rename: { "nmae": "name" } } )

This operation renames the sub-document nmae to name:

copy

{ "_id": 1,
  "alias": [ "The American Cincinnatus", "The American Fabius" ],
  "mobile": "555-555-5555",
  "name": { "first" : "george", "last" : "washington" }
}

To rename a field within a sub-document, call the $rename operator using the dot notation to refer to the field. Include the name of the sub-document in the new field name to ensure the field remains in the sub-document:

copy

db.students.update( { _id: 1 }, { $rename: { "name.first": "name.fname" } } )

This operation renames the sub-document field first to fname:

copy

{ "_id" : 1,
  "alias" : [ "The American Cincinnatus", "The American Fabius" ],
  "mobile" : "555-555-5555",
  "name" : { "fname" : "george", "last" : "washington" }
}

To rename a field within a sub-document and move it to another sub-document, call the $rename operator using the dot notation to refer to the field. Include the name of the new sub-document in the new name:
copy
```
db.students.update( { _id: 1 }, { $rename: { "name.last": "contact.lname" } } )
```
This operation renames the sub-document field last to lname and moves it to the sub-document contact:
copy
```
{ "_id" : 1,
  "alias" : [ "The American Cincinnatus", "The American Fabius" ],
  "contact" : { "lname" : "washington" },
  "mobile" : "555-555-5555",
  "name" : { "fname" : "george" }
}
```
If the new field name does not include a sub-document name, the field moves out of the subdocument and becomes a regular document field.

Consider the following behavior when the specified old field name does not exist:

When renaming a single field and the existing field name refers to a non-existing field, the $rename operator does nothing, as in the following:
copy
```
db.students.update( { _id: 1 }, { $rename: { 'wife': 'spouse' } } )
```
This operation does nothing because there is no field named wife.

When renaming multiple fields and all of the old field names refer to non-existing fields, the $rename operator does nothing, as in the following:

copy

db.students.update( { _id: 1 }, { $rename: { 'wife': 'spouse',
                                             'vice': 'vp',
                                             'office': 'term' } } )

This operation does nothing because there are no fields named wife, vice, and office.

When renaming multiple fields and some but not all old field names refer to non-existing fields, the $rename operator performs the following operations:

Changed in version 2.2.
- Renames the fields that exist to the specified new field names.
- Ignores the non-existing fields.
Consider the following query that renames both an existing field mobile and a non-existing field wife. The field named wife does not exist and $rename sets the field to a name that already exists alias.
copy
```
db.students.update( { _id: 1 }, { $rename: { 'wife': 'alias',
                                             'mobile': 'cell' } } )
```
This operation renames the mobile field to cell, and has no other impact action occurs.
copy
```
{ "_id" : 1,
  "alias" : [ "The American Cincinnatus", "The American Fabius" ],
  "cell" : "555-555-5555",
  "name" : { "lname" : "washington" },
  "places" : { "d" : "Mt Vernon", "b" : "Colonial Beach" }
}
```
Note

Before version 2.2, when renaming multiple fields and only some (but not all) old field names refer to non-existing fields:
- For the fields with the old names that do exist, the $rename operator renames these fields to the specified new field names.
- For the fields with the old names that do not exist:
  - if no field exists with the new field name, the $rename operator does nothing.
  - if fields already exist with the new field names, the $rename operator drops these fields.
Consider the following operation that renames both the field mobile, which exists, and the field wife, which does not exist. The operation tries to set the field named wife to alias, which is the name of an existing field:
copy
db.students.update( { _id: 1 }, { $rename: { 'wife': 'alias', 'mobile': 'cell' } } )
Before 2.2, the operation renames the field mobile to cell and drops the alias field even though the field wife does not exist:
copy
{ "_id" : 1, "cell" : "555-555-5555", "name" : { "lname" : "washington" }, "places" : { "d" : "Mt Vernon", "b" : "Colonial Beach" } }

← $inc $setOnInsert →