/ /

更新（数据库命令）

定义

update: update 命令修改集合中的文档。一个 update 命令可以包含多条更新语句。
提示
在mongosh中，该命令还运行通过 updateOne() 、 updateMany() 、 replaceOne() 、 findOneAndReplace()和findOneAndUpdate()辅助方法运行。
辅助方法对 mongosh 用户来说很方便，但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段，请使用数据库命令。

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

注意

所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息，请参阅不支持的命令。

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

在版本8.0中进行了更改。

该命令具有以下语法：

db.runCommand(
   {
      update: <collection>,
      updates: [
         {
           q: <query>,
           u: <document or pipeline>,
           c: <document>, // Added in MongoDB 5.0
           upsert: <boolean>,
           multi: <boolean>,
           collation: <document>,
           arrayFilters: <array>,
           hint: <document|string>,
           sort: <document>
         },
         ...
      ],
      ordered: <boolean>,
      maxTimeMS: <integer>,
      writeConcern: { <write concern> },
      bypassDocumentValidation: <boolean>,
      comment: <any>,
      let: <document> // Added in MongoDB 5.0
   }
)

命令字段

该命令接受以下字段：

字段

类型

说明

update

字符串

目标集合的名称。

updates

阵列

对指定集合执行的一个或多个更新语句的大量。有关更新语句的详细信息，请参阅更新语句。

ordered

布尔

可选。如果为 true，则当更新语句失败时，则会返回而不执行剩余的更新语句。如果为 false，则当更新失败时，继续执行剩余的更新语句（如果有）。默认为 true。

maxTimeMS

non-negative integer

可选。

指定时间限制（以毫秒为单位）。如果您未指定 maxTimeMS 值，操作将不会超时。如果值为 0 ，则显式指定默认无限制行为。

MongoDB 使用与 db.killOp() 相同的机制终止超过分配的时间限制的操作。MongoDB 仅在指定的中断点之一中终止操作。

writeConcern

文档

可选。表达命令写关注（write concern） update的文档。省略以使用默认的写关注（write concern）。

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

bypassDocumentValidation

布尔

可选。启用 update 可在此操作期间绕过模式验证。这样便可更新不符合验证要求的文档。

comment

any

可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置：

mongod 日志消息，位于 attr.command.cursor.comment 字段中。
command.comment 字段中的数据库分析器输出。
currentOp 输出，在 command.comment 字段。

注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。

let

文档

可选。

指定包含变量列表的文档。这样可以将变量与查询文本分开，从而提高命令的可读性。

文档语法为：

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

变量设置为表达式返回的值，并且之后不能再进行更改。

要访问命令中的变量值，请使用双美元符号前缀 ($$) 以及 $$<variable_name> 形式的变量名称。例如：$$targetTotal。

有关完整示例，请参阅在 let选项或c 字段中使用变量。

版本 5.0 中的新增功能。

sort

文档

可选。

在应用更新之前对文档进行排序。

如果 sort 参数不是文档，则操作错误。

MongoDB 不按特定顺序将文档存储在集合中。对包含重复值的字段进行排序时，可能会以任何顺序返回包含这些值的文档。

$sort 操作不是“稳定排序”，这意味着具有等效排序键的文档在输出中不一定能保持与输入相同的相对顺序。

如果排序条件中指定的字段在两个文档中都不存在，那么它们排序所依据的值是相同的。这两个文档可以以任何顺序返回。

如果需要一致的排序顺序，请在排序中至少纳入一个包含唯一值的字段。最简单方法是在排序查询中纳入 _id 字段。

有关更多信息，请参阅排序一致性。

8.0版本新增。

无法将 sort 与 multi: true 一起使用。

有关 sort 示例，请参阅使用排序更新操作。

更新语句

updates 数组的每个元素都是一个更新语句文档。每个文档都包含以下字段：

字段

类型

说明

文档

匹配要更新文档的查询。使用与 find() 方法中相同的查询选择器。

文档或管道

要应用的修改。该值可为以下任一项：

包含更新操作符表达式的文档、
仅有 <field1>: <value1> 对的替换文档，或者
聚合管道。
- $addFields 及其别名 $set
- $project 及其别名 $unset
- $replaceRoot 及其别名 $replaceWith

有关详情，请参阅行为。

文档

可选。 c只有当 u 是管道时，才能指定。

指定包含变量列表的文档。这样可以将变量与查询文本分开，从而提高命令的可读性。

文档语法为：

{
  <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n>
}

变量设置为表达式返回的值，并且之后不能再进行更改。

要访问命令中的变量值，请使用双美元符号前缀 ($$) 以及 $$<variable_name> 形式的变量名称。例如：$$targetTotal。

要使用变量筛选结果，您必须在 $expr 操作符中访问该变量。

letletc有关使用和变量的完整示例，请参阅在选项或字段中使用变量。

版本 5.0 中的新增功能。

更新插入

布尔

可选。当true update时，将：

如果没有文档与 query 匹配，则创建一个新文档。有关详细信息，请参阅更新或插入行为。
更新与 query 匹配的单份文档。

如果 upsert 和 multi 均为 true，并且没有文档与查询匹配，则更新操作仅插入单个文档。

要避免多次更新或插入，请确保 query字段具有唯一索引。有关示例，请参阅使用唯一索引进行更新或插入。

默认值为 false；即，在未找到匹配项时不插入新文档。

multi

布尔

可选。如果 true，则更新所有符合查询条件的文档。如果 false，则将更新限制为满足查询条件的一份文档。默认为 false。

更新多个文档时，如果单个文档更新失败，则其他文档也不会更新。有关此行为的更多详细信息，请参阅多次更新失败。

collation

文档

可选。

指定用于操作的排序规则。

排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号规则。

排序规则选项的语法如下：

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

指定排序规则时，locale 字段为必填字段；所有其他排序规则字段均为可选字段。有关字段的说明，请参阅排序规则文档。

如果未指定排序规则，但集合具有默认排序规则（请参阅 db.createCollection()），则操作将使用为集合指定的排序规则。

如果没有为收集或操作指定排序规则，MongoDB 将使用先前版本中使用的简单二进制比较来进行字符串比较。

您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果执行带排序的查找，则不能使用一种排序规则进行查找而另一种排序规则进行排序。

arrayFilters

阵列

可选。一个筛选器文档数组，确定要针对数组字段的更新操作修改哪些数组元素。

在更新文档中，使用 $[<identifier>] 筛选后的位置运算符来定义标识符，然后在数组筛选文档中引用该标识符。如果更新文档中未包含某一标识符，则无法获得该标识符的数组筛选文档。

<identifier> 必须以小写字母开头，且只能包含字母数字字符。

您可以在更新文档中多次包含相同的标识符；但对于更新文档中的每个不同标识符 ($[identifier])，您必须准确指定一个对应的数组筛选器文档。也就是说，不能为同一个标识符指定多个数组筛选器文档。例如，如果更新语句包含标识符 x（可能多次），则不能为 arrayFilters 指定以下内容，其中包括 x 的 2 个单独的筛选器文档：

// INVALID
[
  { "x.a": { $gt: 85 } },
  { "x.b": { $gt: 80 } }
]

但是，您可以在单个过滤器文档中的同一标识符上指定复合条件，例如以下示例：

// Example 1
[
  { $or: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 2
[
  { $and: [{"x.a": {$gt: 85}}, {"x.b": {$gt: 80}}] }
]
// Example 3
[
  { "x.a": { $gt: 85 }, "x.b": { $gt: 80 } }
]

有关示例，请参阅为数组更新操作指定 arrayFilters。

提示

文档或字符串

可选。指定用于支持查询谓词的索引的文档或字符串。

该选项可以采用索引规范文档或索引名称字符串。

如果指定不存在的索引，则操作出错。

有关示例，请参阅为更新操作指定 hint。

该命令返回一份包含操作状态的文档。例如：

{
   "ok" : 1,
   "nModified" : 0,
   "n" : 1,
   "upserted" : [
      {
         "index" : 0,
         "_id" : ObjectId("52ccb2118908ccd753d65882")
      }
   ]
}

有关输出字段的详细信息，请参阅输出。

访问控制

在使用 authorization 运行的部署中，用户必须具有包含以下特权的访问权限：

update 针对指定集合的操作。
find 针对指定集合的操作。
insert 针对指定集合的操作。

内置角色readWrite提供所需的特权。

行为

限制

如果设置 multi: true，请仅将 update 命令用于幂等操作。

使用更新操作符表达式文档进行更新

更新语句字段 u 可以接受只包含更新运算符表达式的文档。例如：

updates: [
   {
     q: <query>,
     u: { $set: { status: "D" }, $inc: { quantity: 2 } },
      ...
   },
   ...
]

然后，update 命令仅更新文档中的相应字段。

使用替换文档进行更新

更新语句字段 u 字段可以接受替换文档，即该文档仅包含 field:value 表达式。例如：

updates: [
   {
      q: <query>,
      u: { status: "D", quantity: 4 },
      ...
   },
   ...
]

然后，update 命令将匹配文档替换为更新文档。update 命令只能替换单个匹配文档，即 multi 字段不能为 true。update 命令不会替换 _id 值。

多次更新失败

如果在multi参数设置为 true 的更新命令中单个文档无法更新，则不会再作为该命令的一部分更新任何文档。

示例，sample_mflix.movies 集合包含具有imdb.rating 字段的电影。在集合上创建一个文档验证器，规则是 moviesimdb.rating值必须小于或等于10 ：

db.runCommand( 
   { 
      update: "movies",
      updates: [
      {
         q: { 
            year: { $gte: 2000, $lte: 2005 },
            "imdb.rating": { $type: "number" }
         }, 
         u: { $inc: { "imdb.rating": 1 } },
         multi: true
      }
      ]
   }
)

如果任何电影的评分已经为 10，则增加该电影的评分将违反验证器规则（评分 > 10）。发生这种情况时，即使有数千个文档与查询匹配，更新也会停止，并且不会更新更多文档。

注意

如果更新了匹配文档的子集，例如更新会导致某些文档无法通过模式验证，update 命令返回的 nModified 值可能不准确。

使用聚合管道进行更新

更新语句的 u 字段可以接受聚合管道 [ <stage1>, <stage2>, ... ]，用于指定要执行的修改。该管道可以由以下阶段组成：

$addFields 及其别名 $set
$project 及其别名 $unset
$replaceRoot 及其别名 $replaceWith

使用聚合分析管道可以进行更具表现力的更新声明，例如基于当前字段值的Express条件更新或使用另一个字段的值更新一个字段。

例如：

updates: [
   {
      q: <query>,
      u: [
        { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } },
        { $unset: [ "misc1", "misc2" ] }
      ],
      ...
   },
   ...
]

注意

管道中使用的 $set 和 $unset 分别指聚合阶段 $set 和 $unset，而不是更新操作符 $set 和 $unset。

有关示例，请参阅使用聚合管道进行更新。

使用唯一索引进行 upsert

除非有唯一索引来防止重复，否则 upsert 可能会创建重复的文档。

以某一情况为例，其中不存在名为 Andy 的文档，且多个客户端大致会在同一时间发出以下命令：

db.runCommand(
   {
     update: "people",
     updates: [
       { q: { name: "Andy" }, u: { $inc: { score: 1 } }, multi: true, upsert: true }
     ]
   }
)

如果所有 update 操作在任何客户端成功插入数据之前完成了查询阶段，且 name 字段上没有唯一索引，则每个 update 操作都可能导致插入，从而使用 name: Andy 创建多个文档。

name 字段上的唯一索引可确保仅创建一个文档。通过此唯一索引，多个 update 操作此时便有如下行为：

只需执行一次 update 操作就能成功插入一个新文档。
其他 update 操作要么更新新插入的文档，要么由于唯一键冲突而失败。
为了让其他 update 操作更新新插入的文档，必须满足以下所有条件：
- 目标collection具有会导致重复键错误的唯一索引。
- 更新操作不是updateMany或multi是false 。
- 更新匹配条件为：
  - 单个相等谓词。例如 { "fieldA" : "valueA" }
  - 等式谓词的逻辑 AND。例如 { "fieldA" : "valueA", "fieldB" : "valueB" }
- 相等谓词中的字段与唯一索引键模式中的字段匹配。
- 更新操作不会修改唯一索引键模式中的任何字段。

下表显示了upsert操作的示例，当发生键冲突时，这些操作要么导致更新，要么失败。

唯一索引键模式

更新操作

结果

{ name : 1 }

db.people.updateOne(
   { name: "Andy" },
   { $inc: { score: 1 } },
   { upsert: true }
)

匹配文档的score字段递增 1。

{ name : 1 }

db.people.updateOne(
   { name: { $ne: "Joe" } },
   { $set: { name: "Andy" } },
   { upsert: true }
 )

操作失败是因为它修改了唯一索引键模式 ( name ) 中的字段。

{ name : 1 }

db.people.updateOne(
  { name: "Andy", email: "andy@xyz.com" },
  { $set: { active: false } },
  { upsert: true }
)

操作失败，因为等值谓词字段（ name 、 email ）与索引键字段（ name ）不匹配。

限制

对于 updates 数组中的每个更新元素，查询和更新大小（即 q 和u）之和必须小于或等于最大 BSON 文档大小。

updates 数组中更新语句的总数必须小于或等于最大批量大小。

模式验证

update 命令新增了对 bypassDocumentValidation 选项的支持，从而允许您在附带验证规则的集合中插入或更新文档时绕过模式验证。

分片集合

`upsert` 分片集合

要在分片集合上使用 update 和 multi: false，

如果未指定 upsert: true，则过滤器 q 必须在 _id 字段中包含等值匹配项或以单个分片为目标（例如通过包含分片键）。
如果您指定 upsert: true，则过滤器 q 必须在分片键上包含等值匹配项。
但是，分片集合中的文档可能缺少分片键字段。要定位缺失分片键的文档，可将 null 等值匹配与其他过滤条件（例如针对 _id 字段）结合使用。例如：
```
{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key
```

替换文档

替换文档时，update 会首先尝试使用查询过滤器来定位分片。如果该操作无法通过查询过滤器来定位单个分片，则会尝试通过替换文档来定位。

分片键修改

您可以更新文档的分片键值，除非分片键字段是不可变的 _id 字段。

要修改现有的分片键值（使用update）：

必须在 mongos 上运行。请勿直接对分片发出此操作。
你必须在事务中运行，或者以可重试写入的形式运行。
必须指定 multi: false。
你必须在完整分片键上包含相等查询筛选条件。

提示

由于缺失的键值是作为 null 相等匹配的一部分返回的，因此为避免更新空值键，请酌情纳入其他查询条件（例如 _id 字段）。

另请参阅针对分片集合的 upsert。

缺少分片键

分片集合中的文档可能缺少分片键字段。要使用 update 来设置文档缺失的分片键，则必须在 mongos 上运行。请勿直接对分片发出此操作。

此外，以下要求也适用：

任务	要求
若要设为 `null`	可以指定 `multi: true`。如果指定了 `upsert: true`，则需要对完整的分片键使用相等筛选器。
要设置为非 `null` 值：	必须在事务中或作为可重试写入执行。必须指定 `multi: false`。如果满足以下任一条件，则需使用针对完整分片键的相等筛选器： `upsert: true`，或如果使用替换文档，并且新的分片键值属于另一个分片。

提示

由于缺失的键值是作为 null 相等匹配的一部分返回的，因此为避免更新空值键，请酌情纳入其他查询条件（例如 _id 字段）。

另请参阅：

事务

update 可以在分布式事务中使用。

重要

在大多数情况下，与单文档写入操作相比，分布式事务会产生更高的性能成本，并且分布式事务的可用性不应取代有效的模式设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）仍然是数据和使用案例的最佳选择。换言之，对于许多场景，适当的数据建模将最大限度地减少对分布式事务的需求。

有关其他事务使用注意事项（如运行时间限制和 oplog 大小限制），另请参阅生产注意事项。

在 ACID 事务中进行更新或插入 (upsert)

如果分布式事务不是跨分片写入事务，则可以在该事务中创建集合和索引。

具有 upsert: true 的 update 可以在现有集合或不存在的集合上运行。如果在不存在的集合上运行，该操作将创建集合。

提示

在事务中创建集合和索引

写关注和事务

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

示例

本页上的示例使用 sample_mflix示例数据集中的数据。有关如何将此数据集加载到自管理MongoDB 部署中的详细信息，请参阅加载示例数据集。如果对示例数据库进行了任何修改，则可能需要删除并重新创建数据库才能运行本页上的示例。

更新一份文档的特定字段

使用更新操作符仅更新文档的指定字段。

示例，sample_mflix数据库的 movies集合中的文档包含 title、year 和 num_mflix_comments 等字段。

以下命令使用 $set 和 $inc 更新运算符，以更新文档的 year 和 num_mflix_comments 字段，其中 title 等于 "The Godfather"：

db.runCommand(
   {
      update: "movies",
      updates: [
         {
            q: { title: "The Godfather" }, u: { $set: { year: 1972 }, $inc: { num_mflix_comments: 1 } }
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

由于 <update> 文档未指定可选的 multi 字段，因此即使有多个文档符合 q 匹配条件，更新也只会修改一个文档。

有关详细信息，请参阅输出。

更新多份文档的特定字段

使用更新运算符仅更新文档的指定字段，并在更新语句中包含设置为 true 的 multi 字段。

示例，sample_mflix数据库的 movies集合中的文档包含 year 和 num_mflix_comments 等字段。

以下命令使用$inc 更新操作符递增num_mflix_comments 上映的所有电影的1924 字段：

db.runCommand(
   {
      update: "movies",
      updates: [
         { 
            q: { year: 1924 }, 
            u: { $inc: { num_mflix_comments: 1 }, $set: { classic: true, era: "silent" } }, 
            multi: true 
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

由于 multi字段设立为 true，因此更新会修改与 q字段中指定的查询匹配的所有 6 文档，并返回以下输出：

{ n: 6, nModified: 6, ok: 1 }

有关详细信息，请参阅输出。

使用聚合管道进行更新

update命令可以使用聚合管道进行更新。该管道可以由以下阶段组成：

$addFields 及其别名 $set
$project 及其别名 $unset
$replaceRoot 及其别名 $replaceWith

使用聚合分析管道可以进行更具表现力的更新声明，例如基于当前字段值的Express条件更新或使用另一个字段的值更新一个字段。

示例 1

以下示例使用聚合分析管道使用文档中其他字段的值来修改字段。

sample_mflix数据库的 users集合中的文档包含 name 和 email 等字段。

以下更新操作使用聚合管道向特定用户的文档添加新字段：

db.runCommand(
   {
      update: "users",
      updates: [
         { 
            q: { name: "Robert Baratheon" },  
            u: [ 
               { $set: { full_info: { $concat: [ "$name", " - ", "$email" ] } } },
               { $set: { status: "active" } }
            ], 
            multi: false
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

注意

$set管道中使用的操作是指聚合阶段$set ，而不是更新操作符$set 。

示例 2

聚合分析管道允许更新根据当前字段值执行条件更新以及使用当前字段值计算单独的字段值。

sample_mflix数据库的 movies集合中的文档具有 year字段。

以下示例使用聚合管道计算“火车大劫案”的年龄，并根据发布时间分配时代分类。

db.runCommand(
   {
      update: "movies",
      updates: [
         { 
            q: { title: "The Great Train Robbery" },  
            u: [ 
                  { $set: { age: { $subtract: [ 2026, "$year" ] } } },
                  { $set: { era: { $switch: { 
                                       branches: [
                                             { case: { $lt: [ "$year", 1960 ] }, then: "Classic" },
                                             { case: { $lt: [ "$year", 1980 ] }, then: "Golden Age" },
                                             { case: { $lt: [ "$year", 2000 ] }, then: "Modern" },                                                   
                                             { case: { $gte: [ "$year", 2000 ] }, then: "Contemporary" }
                                       ],
                                       default: "Unknown" 
                  } } } } 
            ], 
            multi: false
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

注意

管道中使用的 $set 指的是聚合阶段 $set，而不是更新操作符 $set。

第一个阶段：: $set阶段根据age 2026和电影发布年份之间的差值计算新字段。有关更多信息，请参阅$subtract 。
第二阶段: 阶段使用条件逻辑根据 $set字段计算新字段era year$switch。有关$switch 聚合操作符的更多信息，请参阅。

批量更新

以下示例在单个命令中执行多个更新操作，以更新现有文档和插入新文档。操作：

将 2015 的高度评价恐怖电影标记为 featured
将来自 2012 的剧情片和爱情片归类为 melodrama
如果 2024 中不存在，则更新插入一部新的科幻电影

db.runCommand(
   {
      update: "movies",
      updates: [
         // Update highly-rated Horror movies from 2015
         { 
            q: { year: 2015, genres: "Horror", "imdb.rating": { $gte: 7 } }, 
            u: { $set: { featured: true } },
            multi: true
         },
         // Update short Drama/Romance movies from 2012
         { 
            q: { year: 2012, genres: { $all: ["Drama", "Romance"] }, runtime: { $lt: 90 } }, 
            u: { $set: { category: "melodrama" } },
            multi: true
         },
         // Upsert a new movie from 2026
         { 
            q: { title: "A New Movie", year: 2026 }, 
            u: { 
               $set: { 
                  genres: ["Sci-Fi", "Adventure"],
                  runtime: 142,
                  "imdb.rating": 8.5,
                  featured: true
               }
            },
            upsert: true
         }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

返回的文档显示该命令修改了现有文档并通过更新或插入（upsert）插入了新文档。有关详细信息，请参阅输出。

{
  n: 16,
  upserted: [
    {
      index: 2,
      _id: ObjectId('69861e680e6ea1f51160fe1c')
    }
  ],
  nModified: 15,
  ok: 1,
  '...': '...'
}

指定排序规则。

排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号规则。

sample_mflix数据库的 movies集合中的文档包含 title 和 year 等字段。

以下操作使用排序规则来执行不区分大小写的搜索。该查询以小写形式搜索 "the godfather"，但使用 strength: 1 排序规则时，无论大小写如何，该查询都会匹配 "The Godfather"：

db.runCommand({
  update: "movies",
  updates: [
    {
      q: { title: "the godfather" },
      u: { $set: { featured: true } },
      collation: { locale: "en", strength: 1 }
    }
  ]
})

`arrayFilters`为数组更新操作指定

更新数组字段时，您可以指定 arrayFilters 确定要更新哪些数组元素。

更新匹配`arrayFilters` 条件的元素

sample_mflix数据库的 movies集合中的文档具有 languages大量字段。

以下示例更新其 languages大量中包含 "English" 的所有电影。该操作会将 "English" 替换为 "EN"。

db.runCommand( {
   update: "movies",
   updates: [
      { q: { languages: "English" }, u: { $set: { "languages.$[element]" : "EN" } }, arrayFilters: [ { "element": "English" } ], multi: true}
   ]
} )

更新文档数组的特定元素

sample_mflix数据库的 movies集合中的文档有一个列出演员姓名的 cast大量。

以下示例更新其 cast大量中包含 "Al Pacino" 的所有电影，将 "Al Pacino" 替换为 "REDACTED"。 arrayFilters 选项指定要更新的大量元素：

db.runCommand({
   update: "movies",
   updates: [
      { q: { cast: "Al Pacino" }, u: { $set: { "cast.$[elem]" : "REDACTED" } }, arrayFilters: [ { "elem": "Al Pacino" } ], multi: true }
   ]
})

该操作会更新 cast大量中具有 "Al Pacino" 的所有 40 电影，并将其名称替换为 "REDACTED"。

`hint`为更新操作指定

sample_mflix数据库的 movies集合中的文档包含 year 和 num_mflix_comments 等字段。

在集合上创建以下索引：

[
   db.movies.createIndex( { year: 1 } ),
   db.movies.createIndex( { num_mflix_comments: 1 } )
]

以下更新操作递增 "The Great Train Robbery" 的 num_mflix_comments字段，并明确提示使用索引{ year: 1 }：

注意

如果指定不存在的索引，则操作出错。

db.runCommand({
   update: "movies",
   updates: [
      { q: { title: "The Great Train Robbery" }, u: { $inc: { "num_mflix_comments": 1 } }, hint: { year: 1 }, multi: false }
   ]
})

要查看使用的索引，可以在更新操作上运行explain 。示例，以下内容解释了针对num_mflix_comments 5或更高版本发布的评论为或更少的电影的2000 递增的更新：

db.runCommand(
   {
      explain: {
         update: "movies",
         updates: [ 
         { q: { "num_mflix_comments": { $lte: 5 }, "year": { $gte: 2000 } }, u: { $inc: { "num_mflix_comments": 1 } }, hint: { year: 1 }, multi: true }
         ]
      },
      verbosity: "queryPlanner"
   }
)

explain 不修改文档。

在`let` 选项或字段中使用变量`c`

版本 5.0 中的新增功能。

变量可以在 let 选项或 c 字段中定义，并在 updates 数组中访问。

注意

要使用变量筛选结果，您必须在 $expr 操作符中访问该变量。

sample_mflix数据库的 movies集合中的文档包含 title 和 year 等字段。

以下示例使用 let 选项定义变量，用于查找电影并将新字段添加到电影中。

db.runCommand( {
   update: "movies",
   updates: [
      { q: { $expr: { $eq: [ "$title", "$$movieTitle" ] } },
         u: [ { $set: { franchise: "$$franchiseName" } } ] }
   ],
   let : { movieTitle: "The Godfather", franchiseName: "The Godfather Trilogy" }
} )

下一个示例在 c 中定义 movieTitle 和 franchiseName 变量，并使用这些变量添加 franchise字段。

db.runCommand( {
   update: "movies",
   updates: [
      { q: { $expr: { $eq: [ "$title", "$$movieTitle" ] } },
         u: [ { $set: { franchise: "$$franchiseName" } } ],
         c: { movieTitle: "The Godfather", franchiseName: "The Godfather Trilogy" } }
      ]
} )

输出

返回的文档包含以下字段的子集：

update.ok: 命令的状态。

update.n

update 命令接受一个文档更新数组，其中一些可以是更新插入 (upsert)。对于更新，n 是选定进行更新的文档数量。对于更新插入，插入文档的 n 为 1。服务器为所有更新和更新插入增加 n 值，并将总数返回为 update.n。

如果更新操作不会导致文档发生任何更改，例如，$set 表达式将数值更新为当前值，n 可大于 nModified.

update.nModified: 更新的文档数量。如果更新操作导致文档未发生变化，例如将字段的值设置为其当前值，则 nModified 可以小于 n。
注意
如果更新了匹配文档的子集，例如更新会导致某些文档无法通过模式验证，update 命令返回的 nModified 值可能不准确。

update.upserted

文档数组，包含通过更新插入的每个文档的信息，更新时使用 upsert: true。

每个文档均包含以下信息：

update.upserted.index: 一个整数，用于标识 updates 数组中带有 upsert:true 语句的更新，该数组使用从零开始的索引。

update.upserted._id: 所添加文档的 _id 值。

update.writeErrors

包含在更新操作过程中遇到的任何错误的相关信息的文档数组。writeErrors 数组包含每个出错的更新语句的错误文档。

每个错误文档都包含以下字段：

update.writeErrors.index: 一个整数，用于标识 updates 数组中的更新语句，该数组使用从零开始的索引。

update.writeErrors.code: 标识错误的整数值。

update.writeErrors.errmsg: 错误描述。

update.writeConcernError

描述与写关注（write concern）相关的错误的文档。

在版本7.0.6 中进行了更改：（也适用于 6.0.14和5.0.30 ）：当update 在mongos 上执行时，即使发生一个或多个写入错误，也始终会报告写关注（write concern）错误。在以前的版本中，发生写入错误可能会导致不报告写关注（writeupdate concern）错误。

writeConcernError文档包含以下字段：

update.writeConcernError.code: 一个整数值，用于标识写关注错误原因。

update.writeConcernError.errmsg: 写关注错误原因的描述。

update.writeConcernError.errInfo.writeConcern

用于相应操作的写关注对象。有关写关注对象字段的信息，请参阅写关注规范。

写关注对象还可能包含以下字段，指示写关注的来源：

update.writeConcernError.errInfo.writeConcern.provenance

一个表示写关注来源（称为写关注provenance）的字符串值。下表显示该字段的可能值及其有效位数：

来源	说明
`clientSupplied`	应用程序中指定了写关注。
`customDefault`	写入关注源自自定义的默认值。请参阅 `setDefaultRWConcern`。
`getLastErrorDefaults`	写关注源自副本集的 `settings.getLastErrorDefaults` 字段。
`implicitDefault`	在没有所有其他写入关注规范的情况下，写入关注源自服务器。

在版本8.1.2中进行了更改。

当 update 在分片集群中的 mongos 上执行时，即使出现一个或多个其他错误，响应中也始终会报告 writeConcernError。在以前的版本中，其他错误有时会导致 update 不报告写关注（write concern）错误。

示例，如果文档验证失败，触发 DocumentValidationFailed 错误，并且还发生写关注（write concern）错误，则 DocumentValidationFailed 错误和 writeConcernError 都会在响应的顶级字段中返回。

除了上述特定的更新返回字段外，db.runCommand() 还包括其他信息：

针对副本集：optime、electionId、$clusterTime 和 operationTime。
对于分片集群：operationTime 和 $clusterTime。

有关这些字段的详细信息，请参阅 db.runCommand Response。

使用排序更新操作

sample_mflix数据库的 movies集合中的文档包含 year、title 和 num_mflix_comments 等字段。

以下示例查找 1972 中的所有电影，并更新评论最多的电影。

db.runCommand( {
   update: "movies",
   updates: [ {
      // Find movies from 1972
      q: { year: 1972 },
      // Add a classic_status field to the found movie
      u: { $set: { classic_status: "Most Discussed 1972 Film" } },
      // Only update one movie
      multi: false,
      // Sort movies by comment count in descending order
      sort: { num_mflix_comments: -1 }
   } ]
} )

该操作仅更新评论最多的 1972 电影。

后退

MapReduce

来年

聚合阶段

定义

提示

兼容性

注意

语法

命令字段

更新语句

返回：

访问控制

行为

限制

使用更新操作符表达式文档进行更新

使用替换文档进行更新

多次更新失败

注意

使用聚合管道进行更新

注意

使用唯一索引进行 upsert

限制

模式验证

分片集合

upsert 分片集合

替换文档

分片键修改

提示

缺少分片键

提示

事务

重要

在 ACID 事务中进行更新或插入 (upsert)

提示

写关注和事务

示例

更新一份文档的特定字段

更新多份文档的特定字段

使用聚合管道进行更新

示例 1

注意

示例 2

注意

批量更新

指定排序规则。

arrayFilters为数组更新操作指定

更新匹配arrayFilters 条件的元素

更新文档数组的特定元素

hint为更新操作指定

注意

在let 选项或 字段中使用变量c

注意

输出

注意

使用排序更新操作

`upsert` 分片集合

`arrayFilters`为数组更新操作指定

更新匹配`arrayFilters` 条件的元素

`hint`为更新操作指定

在`let` 选项或字段中使用变量`c`