Docs Menu

Docs Home → Develop Applications → MongoDB Manual

$rename

On this page

  • Definition
  • Behavior
  • Examples

Definition

$rename

The $rename operator updates the name of a field and has the following form:

{$rename: { <field1>: <newName1>, <field2>: <newName2>, ... } }

The new field name must differ from the existing field name. To specify a <field> in an embedded document, use dot notation.

Consider the following example:

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

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

Behavior

Starting in MongoDB 5.0, update operators process document fields with string-based names in lexicographic order. Fields with numeric names are processed in numeric order. See Update Operators Behavior for details.

The $rename operator logically performs an $unset of both the old name and the new name, and then performs a $set operation with the new name. As such, the operation may not preserve the order of the fields in the document; i.e. the renamed field 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, $rename does nothing (i.e. no operation).

For fields in embedded documents, the $rename operator can rename these fields as well as move the fields in and out of embedded documents. $rename does not work if these fields are in array elements.

Starting in MongoDB 5.0, mongod no longer raises an error when you use an update operator like $rename with an empty operand expression ( { } ). An empty update results in no changes and no oplog entry is created (meaning that the operation is a no-op).

Examples

Create the students collection:

db.students.insertMany( [
   {
     "_id": 1,
     "alias": [ "The American Cincinnatus", "The American Fabius" ],
     "mobile": "555-555-5555",
     "nmae": { "first" : "george", "last" : "washington" }
   },
   {
     "_id": 2,
     "alias": [ "My dearest friend" ],
     "mobile": "222-222-2222",
     "nmae": { "first" : "abigail", "last" : "adams" }
   },
   {
     "_id": 3,
     "alias": [ "Amazing grace" ],
     "mobile": "111-111-1111",
     "nmae": { "first" : "grace", "last" : "hopper" }
   }
] )

The documents contain an error, nmae should be name. The examples in the following sections update the documents in the collection.

Rename a Field

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

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

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

{
  "_id": 1,
  "alias": [ "The American Cincinnatus", "The American Fabius" ],
  "mobile": "555-555-5555",
  "name": { "first" : "george", "last" : "washington" }
}
{
   "_id" : 2,
   "alias" : [ "My dearest friend" ],
   "mobile" : "222-222-2222",
   "name" : { "first" : "abigail", "last" : "adams" }
}
{ "_id" : 3,
  "alias" : [ "Amazing grace" ],
  "mobile" : "111-111-1111",
  "name" : { "first" : "grace", "last" : "hopper" } }

Rename a Field in an Embedded Document

To rename a field in an embedded document, call the $rename operator using the dot notation to refer to 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:

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

This operation renames the embedded field first to fname:

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

Rename a Field That Does Not Exist

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

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

This operation does nothing because there is no field named wife.

Tip

See also:

←  $mul$set →

On this page