$rename

Definition定义

$rename

The $rename operator updates the name of a field and has the following form:$rename运算符更新字段的名称，其形式如下：

{$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.要在嵌入文档中指定<field>，请使用点表示法。

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.此操作将字段nickname重命名为alias，将字段cell重命名为mobile。

Behavior行为

Starting in MongoDB 5.0, update operators process document fields with string-based names in lexicographic order. 从MongoDB 5.0开始，update运算符按照字典顺序处理具有基于字符串的名称的文档字段。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. $rename运算符在逻辑上执行旧名称和新名称的$unset，然后使用新名称执行$set操作。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>.如果文档已经有一个<newName>的字段，$rename运算符将删除该字段，并将指定的<field>重命名为<newName>。

If the field to rename does not exist in a document, $rename does nothing (i.e. no operation).如果文档中不存在要重命名的字段，$rename将不执行任何操作（即不执行操作）。

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运算符可以重命名这些字段，也可以将字段移入和移出嵌入文档。$rename does not work if these fields are in array elements.如果这些字段在数组元素中，$rename将不起作用。

Starting in MongoDB 5.0, mongod no longer raises an error when you use an update operator like $rename with an empty operand expression ( { } ). 从MongoDB 5.0开始，当您使用带有空操作数表达式（{}）的更新运算符（如$rename）时，mongod不再引发错误。An empty update results in no changes and no oplog entry is created (meaning that the operation is a no-op).空更新不会导致任何更改，也不会创建oplog条目（这意味着该操作是无操作）。

Examples实例

Create the students collection:创建students集合：

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.文档中包含错误，nmae应为name。以下各节中的示例将更新集合中的文档。

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

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

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

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

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