Docs 菜单
Docs 主页
/
MongoDB Manual
/
参考
/
操作符
/
Update
/
字段

$rename

在此页面上

  • 定义
  • 语法
  • 行为
  • 示例

定义

$rename

$rename 操作符更新字段的名称。

语法

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

新字段名称必须不同于现有字段名称。 要在嵌入式文档中指定<field> ，请使用点表示法。

考虑以下示例：

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

上述操作将 _id 为 1 的文档中的 nickname 字段重命名为 alias，并将 cell 字段重命名为 mobile。

行为

在您运行 $rename 操作时，MongoDB 执行以下操作：

  • 从文档中删除旧 <field> 和具有 <newName> 的字段（使用 $unset）。

  • 通过使用 <field> 中的值，使用 <newName> 执行 $set 操作。

原子性(Atomicity)

与更新命令匹配的每个文档是在单独的操作中更新的。更新操作（如 $rename）仅保证单一文档级别的原子性。

字段排序

$rename 操作可能无法保留文档中的字段顺序。

更新处理顺序

从 MongoDB 5.0 开始，更新操作符按字典顺序处理具有基于字符串的名称的文档字段。具有数字名称的字段按数字顺序处理。详情请参阅更新操作符行为。

重命名嵌入式文档字段

$rename 操作符可以将字段移入或移出嵌入式文档。

$rename 不适用于数组中的嵌入式文档。

其他注意事项

  • 如果文档已有带有<newName>的字段，则$rename操作符会删除该字段并将指定的<field>重命名为<newName> 。

  • 如果要重命名的字段在文档中不存在，$rename 不会执行任何操作。

  • 从 MongoDB 5.0 开始，使用带空操作数表达式 ({ }) 的更新操作符（如 $rename）时，mongod 不会再引发错误。空更新不会导致任何变化，也不会创建 oplog 条目（意味着该操作为“无操作”）。

示例

创建 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" }
   }
] )

这些文档包含错误，且 nmae 应为 name。以下各部分中的示例将更新此集合中的文档。

重命名字段

若要重命名字段，请使用字段的当前名称和新名称来调用 $rename 操作符：

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

该操作检查 nmae 字段不为 null 的文档，并更新这些文档以将 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" }
}

对嵌入式文档中的字段重命名

要重命名嵌入式文档中的字段，请使用点表示法来调用 $rename 操作符，从而引用该字段。如果该字段要保留在同一嵌入式文档中，则还需在新名称中使用该点表示法，如下所示：

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

此操作将嵌入式字段 first 重命名为 fname：

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

重命名不存在的字段

重命名字段时，如果现有字段名称引用不存在的字段，则$rename操作符不执行任何操作，如下所示：

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

此操作不执行任何操作，因为没有名为 wife 的字段。

提示

另请参阅：

后退

$mul

来年

$set