$rename

本页内容

定义

语法
行为
示例

定义

$rename: 的$rename运算符用于更新字段的名称。

语法

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

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

考虑以下示例

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

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

行为

当你运行一个 $rename 操作时，MongoDB 会执行以下操作

从文档中删除旧的 <字段> 以及具有 <新名称> 的字段（使用 $unset）。
使用来自 <字段> 的值执行一个 $set 操作，并使用 <新名称>。

原子性

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

字段顺序

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

更新处理顺序

从MongoDB 5.0版本开始，更新运算符按字典顺序处理以字符串命名的字段。数字命名的字段按数字顺序处理。有关详细信息，请参阅更新运算符行为。

重命名嵌套文档字段

$rename运算符可以将字段移动到嵌套文档中或从中移出。

$rename运算符不适用于数组中的嵌套文档。

其他注意事项

如果文档已存在具有新名称的<newName>的字段，则$rename运算符将删除该字段，并将指定的<field>重命名为<newName>。
如果要重命名的字段在文档中不存在，则$rename运算符不执行任何操作。
从MongoDB 5.0开始，mongod在使用类似于$rename的更新操作符并且操作数表达式为空（{ }）时，不再抛出错误。空的更新不会导致任何变化，也不会创建操作日志条目（意味着该操作是一个无操作）。

示例

创建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字段不为空的文档，并将这些文档的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