db.集合。 更新()（mongosh方法）

参数

db.collection.update() 方法采用以下参数：

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

返回：

该方法返回包含操作状态的 WriteResult 文档。

限制

如果设置multi: true，请仅将update()方法用于幂等操作。

在执行 Upsert 的更新中使用 $expr

Attempting to use the $expr operator with the upsert flag set to true generates an error.

分片集合

要在分片集合上使用 db.collection.update() 和 multi: false，必须在 _id 字段中包含精确匹配，或以单个分片为目标（如包含分片键）。

当 db.collection.update() 执行更新操作（而非文档替换操作）时，db.collection.update() 可以将多个分片作为目标。

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

事务

db.collection.update() 可用于分布式事务。

Oplog 条目

如果 db.collection.update() 操作成功更新了文档，则该操作会为 oplog（操作日志）添加一个条目。如果操作失败或者未找到要更新的文档，则该操作不会为 oplog 添加条目。

使用带虚线的 _id 的查询执行更新或插入

When you execute an update() with upsert: true and the query matches no existing document, MongoDB will refuse to insert a new document if the query specifies conditions on the _id field using dot notation.

此限制确保 _id 文档中嵌入的字段顺序定义明确，并且不受查询中指定顺序的约束。

如果尝试以这种方式插入文档， MongoDB会引发错误。

使用重复值进行更新或插入

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

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

name字段上的唯一索引可确保只创建一个文档。使用唯一索引后，多个 db.collection.update() 操作现在会表现出以下行为：

• 正好一个 db.collection.update() 操作成功插入一个新的

  文档。

• 其他 db.collection.update() 操作要么更新新插入的

  文档，否则会因唯一键冲突而失败。

  为了使其他db.collection.update() 操作能够更新新插入的文档，必须满足以下所有条件：

  • 目标集合具有唯一索引，该索引会导致

    重复键错误。

  • 更新操作不是 updateMany 或 multi 是

    false.

  • 更新匹配条件为：

    • 单个相等谓词。例如 { "fieldA" : "valueA" }

    • 等式谓词的逻辑 AND。例如 { "fieldA" : "valueA", "fieldB" : "valueB" }

  • 相等谓词中的字段与

    唯一索引键模式。

  • 更新操作不会修改任何字段

    唯一索引键模式。

数组更新操作

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

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

您可以在更新文档中多次包含相同的标识符；但是，对于更新文档中的每个非重复标识符 ($[identifier])，您必须指定准确一个对应的数组过滤器文档。也就是说，不能为同一标识符指定多个数组过滤器文档。但是，您可以在单个过滤文档中对同一标识符指定复合条件

成功结果

db.collection.update() 方法会返回一个 WriteResult() 对象，其中包含此操作的状态。成功后，WriteResult() 对象将包含匹配查询条件的文档数量、更新插入的文档数量以及修改的文档数量。

写关注错误

如果 db.collection.update() 方法遇到写关注（write concern）错误，结果包括 WriteResult.writeConcernError 字段。

下表解释了 WriteResult.writeConcernError.provenance 的可能值：

与写关注无关的错误

如果 db.collection.update() 方法遇到非写关注（write concern）错误，结果将包括 WriteResult.writeError 字段。

在不存在匹配项时插入一个新文档 (Upsert)

指定选项 upsert: true 时：

• 如果文档符合查询条件，db.collection.update() 将执行更新。

• 如果没有文档符合查询条件，db.collection.update() 将插入单个文档。

  注意

  If multiple, identical upserts are issued at roughly the same time, it is possible for update() used with upsert: true to create duplicate documents. See Upsert with Duplicate Values for more information.

If you specify upsert: true on a sharded collection, you must include the full shard key in the filter. For additional db.collection.update() behavior on a sharded collection, see Sharded Collections.

以下标签页展示了 upsert 修饰符与 update() 的各种用途。

db.movies.update(
   { title: "Test Movie 12345" },
   { 
      $set: {
         title: "Test Movie 12345", 
         year: 2024, 
         genres: [ "Documentary" ],
         rated: "NR"
      }
   },
   { upsert: true }
)

db.movies.update(
   { title: "Test Movie 67890" },   // Query parameter
   {                                // Update document
      $set: { rated: "PG" },
      $setOnInsert: { year: 2024, type: "movie" }
   },
   { upsert: true }                 // Options
)

db.movies.update(
   { title: "Test Movie ABC123" },  // Query parameter
   [                                // Aggregation pipeline
      { $set: { 
         year: 2024, 
         type: "movie",
         rated: "NR",
         lastModified: "$$NOW" 
      } }
   ],
   { upsert: true }   // Options
)

db.movies.update(
   { title: { $in: ["The Godfather", "The Matrix"] } },
   { $set: { test_upsert_field: true } },
   { upsert: true, multi: true }
)

db.movies.update(
   { "title": "Test Movie Unique789" },
   { $set: { year: 2024, type: "movie" } },
   { upsert: true, multi: true }
)

使用聚合管道进行更新

db.collection.update() 方法可以接受指定要执行的修改的聚合管道 [ <stage1>, <stage2>, ... ]。该管道可以由以下阶段组成：

• $addFields 及其别名 $set

• $project 及其别名 $unset

• $replaceRoot 及其别名 $replaceWith

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

db.movies.update(
   { title: "The Godfather" },
   [
      { $set: { 
            displayTitle: { $concat: [ "$title", " (", { $toString: "$year" }, ")" ] },
            lastModified: "$$NOW" 
         } 
      }
   ]
)

db.movies.update(
   { 
      year: 2015,
      "imdb.rating": { $type: "number" },
      "tomatoes.viewer.rating": { $type: "number" }
   },
   [
      { $set: { 
         combinedScore: { 
            $round: [ 
               { $avg: [ 
               { $multiply: [ "$imdb.rating", 10 ] }, 
               { $multiply: [ "$tomatoes.viewer.rating", 10 ] } 
               ] }, 
               1 
            ] 
         }, 
         lastUpdate: "$$NOW" 
         } 
      },
      { $set: { 
         grade: { 
            $switch: {
               branches: [
               { case: { $gte: [ "$combinedScore", 80 ] }, then: "A" },
               { case: { $gte: [ "$combinedScore", 70 ] }, then: "B" },
               { case: { $gte: [ "$combinedScore", 60 ] }, then: "C" },
               { case: { $gte: [ "$combinedScore", 50 ] }, then: "D" }
               ],
               default: "F"
            } 
         } 
         } 
      }
   ],
   { multi: true }
)

为数组更新操作指定 arrayFilters

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

db.movies.update(
   { title: "The Godfather" },
   { $set: { "writers.$[elem]" : { $concat: [ "$elem", " - UPDATED" ] } } },
   {
      arrayFilters: [ { "elem": { $regex: /screenplay/ } } ]
   }
)

为更新操作指定 hint

hint 选项指定 MongoDB 用于更新操作的索引。指定索引可确保更新多个文档时查询计划的一致。此示例使用 sample_mflix 数据库中的现有 movies 集合。

首先，在 year字段上创建索引：

db.movies.createIndex( { year: 1 } )

以下更新操作明确提示使用 { year: 1 }索引来更新2010 -2015 之间的所有电影：

db.movies.update(
   { year: { $gte: 2010, $lte: 2015 } },  // Query parameter
   { $set: { decade: "2010s" } },             // Update document
   { multi: true, hint: { year: 1 } }          // Options
)

要查看使用的索引，请对操作运行 explain：

db.movies.explain().update(
   { title: "The Godfather", year: { $gte: 1970 } },
   { $set: { test_hint_field: true } },
   { hint: { year: 1 } }
)

db.collection.explain().update() 不修改文档。

使用以下项中的变量： let

要定义可在命令中其他位置访问的变量，请使用 let 选项。

示例：

• 在 let 选项中定义两个变量：targetTitle（设立为 "The Matrix"）和 newTitle（设立为 "The Matrix Reloaded"）

• 在查询筛选条件中使用 $expr 将文档的 title字段与 $$targetTitle 变量进行比较

• 使用带有 $set 的聚合管道，将 title字段更新为 $$newTitle 的值

db.movies.update(
   { $expr: { $eq: [ "$title", "$$targetTitle" ] } },
   [ { $set: { sequel: "$$sequelTitle" } } ],
   { let : { targetTitle: "The Matrix", sequelTitle: "The Matrix Reloaded" } }
)

覆盖默认写关注

以下对副本集的操作指定了写关注 w: 2，其 wtimeout 为 5000 毫秒。该操作要么在写操作传播到主节点和一个辅助节点后返回，要么在 5 秒后超时。

db.movies.update(
   { num_mflix_comments: { $lte: 10 } },
   { $set: { featured: true } },
   {
      multi: true,
      writeConcern: { w: 2, j: true, wtimeout: 5000 }
   }
)

在主节点 (primary node in the replica set)和至少一个从节点(secondary node from replica set)（如 w: 2 指定）确认写入后，操作成功完成。

分片集群中的写关注错误

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

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

指定排序规则。

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

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

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

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

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

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

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

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

此操作会更新标题以 night 开头的所有电影，并使用 strength: 1 进行不区分大小写的比较：

db.movies.update(
   { title: /^night/i },
   { $set: { updated: true } },
   {
      collation: { locale: "en", strength: 1 },
      multi: true
   }
)