$rename

Definition

  • $rename
  • The $rename operator updates the name of a field and has the following form:
  1. {$rename: { <field1>: <newName1>, <field2>: <newName2>, ... } }

The new field name must differ from the existing field name. Tospecify a <field> in an embedded document, use dotnotation.

Consider the following example:

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

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

Behavior

The $rename operator logically performs an $unsetof both the old name and the new name, and then performs a$set operation with the new name. As such, the operation maynot preserve the order of the fields in the document; i.e. the renamedfield may move within the document.

If the document already has a field with the <newName>, the$rename operator removes that field and renames the specified<field> to <newName>.

If the field to rename does not exist in a document, $renamedoes nothing (i.e. no operation).

For fields in embedded documents, the $rename operator canrename these fields as well as move the fields in and out of embeddeddocuments. $rename does not work if these fields are in arrayelements.

Examples

A collection students contains the following documents where afield nmae appears misspelled, i.e. should be name:

  1. {
  2.   "_id": 1,
  3.   "alias": [ "The American Cincinnatus", "The American Fabius" ],
  4.   "mobile": "555-555-5555",
  5.   "nmae": { "first" : "george", "last" : "washington" }
  6. }
  7.  
  8. {
  9.   "_id": 2,
  10.   "alias": [ "My dearest friend" ],
  11.   "mobile": "222-222-2222",
  12.   "nmae": { "first" : "abigail", "last" : "adams" }
  13. }
  14.  
  15. {
  16.   "_id": 3,
  17.   "alias": [ "Amazing grace" ],
  18.   "mobile": "111-111-1111",
  19.   "nmae": { "first" : "grace", "last" : "hopper" }
  20. }

The examples in this section successively updates the documents in thecollection.

Rename a Field

To rename a field, call the $rename operator with the currentname of the field and the new name:

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

This operation renames the field nmae to name for all documentsin the collection:

  1. {
  2.   "_id": 1,
  3.   "alias": [ "The American Cincinnatus", "The American Fabius" ],
  4.   "mobile": "555-555-5555",
  5.   "name": { "first" : "george", "last" : "washington" }
  6. }
  7.  
  8. {
  9.    "_id" : 2,
  10.    "alias" : [ "My dearest friend" ],
  11.    "mobile" : "222-222-2222",
  12.    "name" : { "first" : "abigail", "last" : "adams" }
  13. }
  14.  
  15. { "_id" : 3,
  16.   "alias" : [ "Amazing grace" ],
  17.   "mobile" : "111-111-1111",
  18.   "name" : { "first" : "grace", "last" : "hopper" } }

Rename a Field in an Embedded Document

To rename a field in an embedded document, call the $renameoperator using the dot notation to referto the field. If the field is to remain in the same embedded document,also use the dot notation in the new name, as in the following:

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

This operation renames the embedded field first to fname:

  1. {
  2.   "_id" : 1,
  3.   "alias" : [ "The American Cincinnatus", "The American Fabius" ],
  4.   "mobile" : "555-555-5555",
  5.   "name" : { "fname" : "george", "last" : "washington" }
  6. }

Rename a Field That Does Not Exist

When renaming a field and the existing field name refers to a fieldthat does not exist, the $rename operator does nothing, as inthe following:

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

This operation does nothing because there is no field namedwife.

See also

db.collection.update(),db.collection.findAndModify()