db.collection.update()

在此页面上

定义

兼容性
语法
访问控制
行为
示例
WriteResult

重要

已弃用的 mongosh 方法

此方法在 mongosh 中已弃用。有关替代方法，请参阅与旧版 mongo Shell 的兼容性更改。

定义

db.collection.update(query, update, options)

修改集合中的一个或多个现有文档。该方法可以修改现有文档的特定字段，也可以完全替换现有文档，具体取决于更新参数。

默认情况下，db.collection.update() 方法会更新单个文档。请包括选项 multi: true ，以更新所有符合查询条件的文档。

兼容性

可以使用 db.collection.update() 查找托管在以下环境中的部署：

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

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

要了解如何使用 Atlas 用户界面更新 MongoDB Atlas 中托管的文档，请参阅编辑一个文档。

语法

5.0 版本中的更改。

db.collection.update() 方法采用以下形式：

db.collection.update(
   <query>,
   <update>,
   {
     upsert: <boolean>,
     multi: <boolean>,
     writeConcern: <document>,
     collation: <document>,
     arrayFilters: [ <filterdocument1>, ... ],
     hint:  <document|string>,
     let: <document> // Added in MongoDB 5.0
   }
)

参数

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

Parameter

类型

说明

查询

文档

更新的选择条件。可以使用与 find() 方法中相同的查询选择器。

当您使用 upsert: true 执行 update() 并且查询与任何现有文档都不匹配时，如果查询使用点表示法在 _id 字段上指定条件，则 MongoDB 将拒绝插入新文档。

update

文档或管道

要应用的修改。可以是以下之一：

Update document	只包含更新操作符表达式。
替换文档	仅包含 `<field1>: <value1>` 对。
聚合管道	仅包含以下聚合阶段： `$addFields` 及其别名 `$set` `$project` 及其别名 `$unset` `$replaceRoot` 及其别名 `$replaceWith`。

有关详细信息和示例，请参阅 Oplog 条目。

更新插入

布尔

可选。当为 true 时，update() 将：

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

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

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

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

多

布尔

可选。如果设为 true，则更新所有符合 query 条件的文档。如果设为 false，则更新一个文档。默认值为 false。有关其他信息，请参阅更新多个文件示例。

writeConcern

文档

可选。表达写关注的文档。省略以使用默认的写关注 w: "majority"

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

有关使用writeConcern的示例，请参阅覆盖默认写关注。

排序规则

文档

可选。

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

有关使用 collation 的示例，请参阅指定排序规则。

arrayFilters

阵列

选修的。大量过滤器文档，用于确定针对大量字段的更新操作要修改哪些大量元素。

在更新文档中，使用 $[<identifier>] 定义标识符，只更新与 arrayFilters 中相应过滤文档匹配的数组元素。

如果更新文档中未包含某一标识符，则无法获得该标识符的数组筛选文档。

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

提示

文档或字符串

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

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

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

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

let

文档

可选。

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

文档语法为：

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

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

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

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

有关使用 let 和变量的完整示例，请参阅在 let 中使用变量。

版本 5.0 中的新增功能。

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

访问控制

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

update 针对指定集合的操作。
find 针对指定集合的操作。
insert 如果操作导致更新插入，则对指定收集执行操作。

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

行为

`$expr`在带有的更新中使用`Upsert`

在 upsert 标志设置为 true 时，尝试使用 $expr 操作符将产生错误。

分片集合

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

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

提示

另请参阅：

findAndModify()

分片集合上的替换文档操作

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

在早期版本中，该操作会尝试使用替换文档定位。

`upsert` 分片集合

对于包含 upsert: true 且在分片集合上的 db.collection.update() 操作，您必须在filter 中包含完整的分片键：

用于更新操作。
进行替换文档操作。

但是，分片集合中的文档可能缺少分片键字段。要定位缺失分片键的文档，可将 null 等值匹配与其他过滤条件（例如针对 _id 字段）结合使用。例如：

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

分片键修改

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

要修改现有的分片键值（使用db.collection.update()）：

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

提示

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

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

缺少分片键

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

此外，以下要求也适用：

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

提示

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

另请参阅：

事务

db.collection.update() 可以在分布式事务中使用。

重要

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

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

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

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

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

提示

另请参阅：

在事务中创建集合和索引

写关注和事务

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

Oplog 条目

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

示例

以下标签页展示了各种常见的 update() 操作。

在 mongosh 中创建 books 集合，其中包含以下文档。此命令首先会删除 books 集合中之前存在的所有文档：

db.books.remove({});
db.books.insertMany([
  {
    "_id" : 1,
    "item" : "TBD",
    "stock" : 0,
    "info" : { "publisher" : "1111", "pages" : 430 },
    "tags" : [ "technology", "computer" ],
    "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "lmn", "rating" : 5 } ],
    "reorder" : false
   },
   {
    "_id" : 2,
    "item" : "XYZ123",
    "stock" : 15,
    "info" : { "publisher" : "5555", "pages" : 150 },
    "tags" : [ ],
    "ratings" : [ { "by" : "xyz", "rating" : 5 } ],
    "reorder" : false
   }
]);

使用更新操作符表达式（`$inc` 和`$set` ）

如果 <update> 文档包含更新操作符修饰符，例如使用 $set 修饰符，则：

<update> 文档只能包含更新操作符表达式。
db.collection.update() 方法只更新文档中的相应字段。
- 要将嵌入式文档或数组作为整体进行更新，请指定该字段的替换值。
- 要更新嵌入式文档或数组中的特定字段，请使用点符号来指定字段。

db.books.update(
   { _id: 1 },
   {
     $inc: { stock: 5 },
     $set: {
       item: "ABC123",
       "info.publisher": "2222",
       tags: [ "software" ],
       "ratings.1": { by: "xyz", rating: 3 }
     }
   }
)

在此操作中：

{ _id: 1 } 的 <query> 参数用于指定要更新哪个文档，
$inc 操作符增加 stock 字段，并且
$set 操作符将替换以下对象的值
- item 字段，
- publisher 字段（位于 info 嵌入式文档中），
- tags 字段，以及
- ratings 数组中的第二个元素。

更新后的文档如下所示：

{
  "_id" : 1,
  "item" : "ABC123",
  "stock" : 5,
  "info" : { "publisher" : "2222", "pages" : 430 },
  "tags" : [ "software" ],
  "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "xyz", "rating" : 3 } ],
  "reorder" : false
}

此操作对应于以下 SQL 语句：

UPDATE books
SET    stock = stock + 5
       item = "ABC123"
       publisher = 2222
       pages = 430
       tags = "software"
       rating_authors = "ijk,xyz"
       rating_values = "4,3"
WHERE  _id = 1

如果 query 参数匹配到多个文档，此操作将只更新一个匹配文档。要更新多个文档，必须将 multi 选项设置为 true。

提示

另请参阅：

$set、$inc，更新操作符点表示法

将元素推送到现有数组 (`$push` )

以下操作使用 $push 更新操作符将新对象附加到 ratings 数组。

db.books.update(
   { _id: 2 },
   {
     $push: { ratings: { "by" : "jkl", "rating" : 2 } }
   }
)

更新后的文档如下所示：

{
  "_id" : 2,
  "item" : "XYZ123",
  "stock" : 15,
  "info" : {
   "publisher" : "5555",
   "pages" : 150
  },
  "tags" : [ ],
  "ratings" : [
   { "by" : "xyz", "rating" : 5 },
   { "by" : "jkl", "rating" : 2 }
  ],
  "reorder" : false
 }

提示

另请参阅：

$push

删除字段 (`$unset` )

以下操作使用$unset操作符通过{ _id: 1 }从文档中删除tags字段。

db.books.update( { _id: 1 }, { $unset: { tags: 1 } } )

更新后的文档如下所示：

{
  "_id" : 1,
  "item" : "TBD",
  "stock" : 0,
  "info" : {
   "publisher" : "1111",
   "pages" : 430
  },
  "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "lmn", "rating" : 5 } ],
  "reorder" : false
 }

没有与$unset直接等效的SQL ，但$unset类似于以下从books表中删除tags字段的SQL命令：

ALTER TABLE books
DROP COLUMN tags

提示

另请参阅：

$unset、 $rename、更新操作符

更新多个文档（`$update` 使用`multi` ）

如果 multi 设置为 true，db.collection.update() 方法会更新所有符合 <query> 标准的文档。multi 更新操作可与其他读/写操作交错进行。

对于所有 stock 小于或等于 10 的文档，以下操作会将 reorder 字段设置为 true。如果匹配文档中不存在 reorder 字段，$set 操作符将添加具有指定值的字段。

db.books.update(
   { stock: { $lte: 10 } },
   { $set: { reorder: true } },
   { multi: true }
)

集合中最终的文档如下：

[
  {
    "_id" : 1,
    "item" : "ABC123",
    "stock" : 5,
    "info" : {
     "publisher" : "2222",
     "pages" : 430
    },
    "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "xyz", "rating" : 3 } ],
    "reorder" : true
   }
   {
     "_id" : 2,
     "item" : "XYZ123",
     "stock" : 10,
     "info" : { "publisher" : "2255", "pages" : 150 },
     "tags" : [ "baking", "cooking" ],
     "reorder" : true
   }
]

此操作对应于以下 SQL 语句：

UPDATE books
SET reorder=true
WHERE stock <= 10

在执行替换时，不能指定 multi: true，并且更新文档仅包含 field:value 表达式。

提示

另请参阅：

$set

如果不存在匹配项，则插入新文档 (`Upsert` )

指定选项 upsert: true 时：

如果文档符合查询条件，db.collection.update() 将执行更新。
如果没有文档符合查询条件，db.collection.update() 将插入单个文档。
注意
如果在大致相同的时间内发出多个相同的更新或插入操作，那么与 upsert: true 一起使用的 update() 有可能会创建重复的文档。有关详细信息，请参阅具有重复值的更新或插入。

如果在一个分片集合上指定 upsert: true，则必须在 filter 中包含完整的分片键。有关分片集合的其他 db.collection.update() 行为，请参阅分片集合。

以下选项卡展示了使用 upsert 修饰符与 update() 的各种用途。

使用替换文档进行更新或插入

如果没有符合查询条件的文档，且 <update> 参数是替换文档（即仅包含字段和值对），则更新将插入一个包含替换文档的字段和值的新文档。

如果您在查询参数或替换文档中指定 _id 字段，则 MongoDB 将在插入的文档中使用该 _id 字段。
如果您未在查询参数或替换文档中指定 _id 字段，则 MongoDB 将使用随机生成的 ObjectId 值来生成 _id 字段。
您不能在查询参数和替换文档中指定不同的 _id 字段值。如果这样做，操作将出错。

例如，如下更新会将更新或插入选项设置为 true：

db.books.update(
   { item: "ZZZ135" },  // Query parameter
   { $set:
      {
         item: "ZZZ135", stock: 5, tags: [ "database" ]  // Replacement document
      }
   },
   { upsert: true }  // Options
)

如果没有与 <query> 参数匹配的文档，则更新操作将插入一个只有替换文档的文档。由于在替换文档或查询文档中未指定 _id 字段，因此该操作会为新文档的 _id 字段创建一个新的唯一 ObjectId。您可以看到操作的 WriteResult 中反映了 upsert：

WriteResult({
  "nMatched" : 0,
  "nUpserted" : 1,
  "nModified" : 0,
  "_id" : ObjectId("5da78973835b2f1c75347a83")
 })

该操作将以下文档插入到 books 集合中（您的 ObjectId 值将有所不同）：

{
  "_id" : ObjectId("5da78973835b2f1c75347a83"),
  "item" : "ZZZ135",
  "stock" : 5,
  "tags" : [ "database" ]
}

使用操作符表达式进行更新或插入 (`$set` )

如果没有符合查询条件的文档，且 <update> 参数是带有更新操作符表达式的文档，则该操作将根据 <query> 参数中的等式子句创建基础文档，并应用 <update> 参数中的表达式。

来自<query>的比较操作将不包含在新文档中。如果新文档不包含_id字段， MongoDB将添加带有ObjectId值的_id字段。

例如，如下更新会将更新或插入选项设置为 true：

db.books.update(
   { item: "BLP921" },   // Query parameter
   {                     // Update document
      $set: { reorder: false },
      $setOnInsert: { stock: 10 }
   },
   { upsert: true }      // Options
)

如果没有文档与查询条件匹配，则该操作将插入以下文档（您的ObjectId值将有所不同）：

{
  "_id" : ObjectId("5da79019835b2f1c75348a0a"),
  "item" : "BLP921",
  "reorder" : false,
  "stock" : 10
}

提示

另请参阅：

$setOnInsert

使用聚合管道进行更新或插入

如果 <update> 参数是聚合管道，更新会根据 <query> 参数中的相等子句创建一个基础文档，然后将管道应用于该文档，创建要插入的文档。如果新文档不包含 _id 字段，MongoDB 将添加具有 ObjectId 值的 _id 字段。

例如，以下 upsert: true 操作指定一个聚合管道，该管道使用

$replaceRoot 阶段，它提供与 $setOnInsert 更新操作符表达式略微相似的行为，
$set 阶段，可以提供与 $set 更新操作符表达式类似的行为，
聚合变量 NOW，解析为当前日期时间，可以提供与 $currentDate 更新操作符表达式相似的行为。

db.books.update(
   { item: "MRQ014", ratings: [2, 5, 3] }, // Query parameter
   [                                       // Aggregation pipeline
      { $replaceRoot: { newRoot: { $mergeObjects: [ { stock: 0 }, "$$ROOT"  ] } } },
      { $set: { avgRating: { $avg: "$ratings" }, tags: [ "fiction", "murder" ], lastModified: "$$NOW" } }
   ],
   { upsert: true }   // Options
)

如果没有与 <query> 参数匹配的文档，该操作会将以下文档插入到 books 集合中（ObjectId 值会有所不同）：

{
   "_id" : ObjectId("5e2921e0b4c550aad59d1ba9"),
   "stock" : 0,
   "item" : "MRQ014",
   "ratings" : [ 2, 5, 3 ],
   "avgRating" : 3.3333333333333335,
   "tags" : [ "fiction", "murder" ],
   "lastModified" : ISODate("2020-01-23T04:32:32.951Z")
}

提示

另请参阅：

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

将与`upsert` `multi`结合使用（匹配）

从 mongosh 开始，将下列文件插入 books 集合：

db.books.insertMany( [
  {
    _id: 5,
    item: "RQM909",
    stock: 18,
    info: { publisher: "0000", pages: 170 },
    reorder: true
  },
  {
    _id: 6,
    item: "EFG222",
    stock: 15,
    info: { publisher: "1111", pages: 72 },
    reorder: true
  }
] )

以下操作同时指定了 multi 选项和 upsert 选项。如果存在匹配的文档，则该操作将更新所有匹配的文档。如果不存在匹配的文档，则该操作将插入一个新文档。

db.books.update(
   { stock: { $gte: 10 } },        // Query parameter
   {                               // Update document
     $set: { reorder: false, tags: [ "literature", "translated" ] }
   },
   { upsert: true, multi: true }   // Options
)

该操作会更新所有匹配的文件，结果如下：

{
   "_id" : 5,
   "item" : "RQM909",
   "stock" : 18,
   "info" : { "publisher" : "0000", "pages" : 170 },
   "reorder" : false,
   "tags" : [ "literature", "translated" ]
}
{
   "_id" : 6,
   "item" : "EFG222",
   "stock" : 15,
   "info" : { "publisher" : "1111", "pages" : 72 },
   "reorder" : false,
   "tags" : [ "literature", "translated" ]
}

将与`upsert` `multi`结合使用（无匹配）

如果集合中没有匹配的文档，操作结果将是使用 <query> 和 <update> 规范中的字段插入一个文档。例如，考虑以下操作：

db.books.update(
  { "info.publisher": "Self-Published" },   // Query parameter
  {                                         // Update document
    $set: { reorder: false, tags: [ "literature", "hardcover" ], stock: 25 }
  },
  { upsert: true, multi: true }             // Options
)

该操作将以下文档插入到 books 集合中（您的 ObjectId 值将有所不同）：

{
  "_id" : ObjectId("5db337934f670d584b6ca8e0"),
  "info" : { "publisher" : "Self-Published" },
  "reorder" : false,
  "stock" : 25,
  "tags" : [ "literature", "hardcover" ]
}

使用虚线`_id` 查询进行更新或插入

当您使用 upsert: true 执行 update() 并且查询与任何现有文档都不匹配时，如果查询使用点表示法在 _id 字段上指定条件，则 MongoDB 将拒绝插入新文档。

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

如果尝试以这种方式插入文档，MongoDB 将引发错误。例如，考虑以下更新操作。由于更新操作指定了 upsert:true ，而查询使用点表示法在 _id 字段上指定了条件，因此在构建要插入的文档时，更新将导致错误。

db.collection.update(
   { "_id.name": "Robert Frost", "_id.uid": 0 },  // Query parameter
   { $set:
      {
         "categories": [ "poet", "playwright" ]  // Replacement document
      }
   },
   { upsert: true }  // Options
)

操作的 WriteResult 会返回以下错误：

WriteResult({
  "nMatched" : 0,
  "nUpserted" : 0,
  "nModified" : 0,
  "writeError" : {
    "code" : 111,
    "errmsg" : "field at '_id' must be exactly specified, field at sub-path '_id.name'found"
  }
})

提示

另请参阅：

WriteResult()

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

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

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

db.people.update(
   { name: "Andy" },
   { $inc: { score: 1 } },
   {
     upsert: true,
     multi: 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 ）不匹配。

提示

另请参阅：

$setOnInsert

使用聚合管道进行更新

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

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

使用文档中其他字段的值修改字段

使用以下文档创建 students 集合：

db.students.insertMany( [
   { "_id" : 1, "student" : "Skye", "points" : 75, "commentsSemester1" : "great at math", "commentsSemester2" : "loses temper", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") },
   { "_id" : 2, "students" : "Elizabeth", "points" : 60, "commentsSemester1" : "well behaved", "commentsSemester2" : "needs improvement", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
] )

假设您不想将 commentsSemester1 和 commentsSemester2 字段分开，而是将它们收集到新的 comments 字段中。以下更新操作使用聚合管道：

添加新的 comments 字段并设置 lastUpdate 字段。
删除集合中所有文档的 commentsSemester1 和 commentsSemester2 字段。

db.members.update(
   { },
   [
      { $set: { comments: [ "$commentsSemester1", "$commentsSemester2" ], lastUpdate: "$$NOW" } },
      { $unset: [ "commentsSemester1", "commentsSemester2" ] }
   ],
   { multi: true }
)

注意

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

第一个阶段：

$set 阶段：

创建一个新的数组字段 comments，其元素是 commentsSemester1 和 commentsSemester2 字段的当前内容，并且
将字段 lastUpdate 设置为聚合变量 NOW 的值。聚合变量 NOW 解析为当前的日期时间值，并在整个管道中保持不变。要访问聚合变量，在变量前加上双美元符号 $$ 并用引号引起来。

第二阶段

$unset 阶段删除 commentsSemester1 和 commentsSemester2 字段。

执行该命令之后，集合中将包含以下文档：

{ "_id" : 1, "student" : "Skye", "status" : "Modified", "points" : 75, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "great at math", "loses temper" ] }
{ "_id" : 2, "student" : "Elizabeth", "status" : "Modified", "points" : 60, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "well behaved", "needs improvement" ] }

提示

另请参阅：

使用聚合管道进行更新。

根据当前字段值执行条件更新

使用以下文档创建 students3 集合：

db.students3.insertMany( [
   { "_id" : 1, "tests" : [ 95, 92, 90 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") },
   { "_id" : 2, "tests" : [ 94, 88, 90 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") },
   { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
] )

使用聚合分析管道，您可以使用计算出的平均成绩和字母等级来更新文档。

db.students3.update(
   { },
   [
     { $set: { average : { $trunc: [ { $avg: "$tests" }, 0 ] }, lastUpdate: "$$NOW" } },
     { $set: { grade: { $switch: {
                           branches: [
                               { case: { $gte: [ "$average", 90 ] }, then: "A" },
                               { case: { $gte: [ "$average", 80 ] }, then: "B" },
                               { case: { $gte: [ "$average", 70 ] }, then: "C" },
                               { case: { $gte: [ "$average", 60 ] }, then: "D" }
                           ],
                           default: "F"
     } } } }
   ],
   { multi: true }
)

注意

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

第一个阶段：

$set 阶段：

根据 tests 字段的平均值计算新字段 average。有关 $avg 聚合操作符的详细信息，请参阅 $avg，有关 $trunc 截断聚合操作符的详细信息，请参阅 $trunc。
将字段 lastUpdate 设置为聚合变量 NOW 的值。聚合变量 NOW 解析为当前的日期时间值，并在整个管道中保持不变。要访问聚合变量，在变量前加上双美元符号 $$ 并用引号引起来。

第二阶段

$set 阶段根据上一阶段计算的 average 字段计算新字段 grade。有关 $switch 聚合操作符的更多信息，请参阅 $switch。

执行该命令之后，集合中将包含以下文档：

{ "_id" : 1, "tests" : [ 95, 92, 90 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 92, "grade" : "A" }
{ "_id" : 2, "tests" : [ 94, 88, 90 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 90, "grade" : "A" }
{ "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 75, "grade" : "C" }

提示

另请参阅：

使用聚合管道进行更新。

`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 不适用于使用聚合管道的更新。

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

要更新符合指定条件的所有数组元素，请使用 arrayFilters 参数。

在 mongosh 中，创建一个 students 集合，其中包含以下文档：

db.students.insertMany( [
   { "_id" : 1, "grades" : [ 95, 92, 90 ] },
   { "_id" : 2, "grades" : [ 98, 100, 102 ] },
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }
] )

要更新 grades 数组中大于或等于 100 的所有元素，请使用带有 arrayFilters 选项的筛选位置运算符 $[<identifier>]：

db.students.update(
   { grades: { $gte: 100 } },
   { $set: { "grades.$[element]" : 100 } },
   {
     multi: true,
     arrayFilters: [ { "element": { $gte: 100 } } ]
   }
)

操作完成后，集合包含以下文档：

{ "_id" : 1, "grades" : [ 95, 92, 90 ] }
{ "_id" : 2, "grades" : [ 98, 100, 100 ] }
{ "_id" : 3, "grades" : [ 95, 100, 100 ] }

更新文档数组的特定元素

还可以使用 arrayFilters 参数更新文档数组中的特定文档字段。

在 mongosh 中，创建一个 students2 集合，其中包含以下文档：

db.students2.insertMany( [
  {
    "_id" : 1,
    "grades" : [
       { "grade" : 80, "mean" : 75, "std" : 6 },
       { "grade" : 85, "mean" : 90, "std" : 4 },
       { "grade" : 85, "mean" : 85, "std" : 6 }
    ]
  },
  {
     "_id" : 2,
     "grades" : [
        { "grade" : 90, "mean" : 75, "std" : 6 },
        { "grade" : 87, "mean" : 90, "std" : 3 },
        { "grade" : 85, "mean" : 85, "std" : 4 }
     ]
  }
] )

要修改 grades 数量中等级大于或等于 85 的所有元素的 mean 字段的值，请将过滤后的位置操作符 $[<identifier>] 与 arrayFilters 结合使用：

db.students2.update(
   { },
   { $set: { "grades.$[elem].mean" : 100 } },
   {
     multi: true,
     arrayFilters: [ { "elem.grade": { $gte: 85 } } ]
   }
)

操作完成后，集合有以下文档：

{
   "_id" : 1,
   "grades" : [
      { "grade" : 80, "mean" : 75, "std" : 6 },
      { "grade" : 85, "mean" : 100, "std" : 4 },
      { "grade" : 85, "mean" : 100, "std" : 6 }
   ]
}
{
   "_id" : 2,
   "grades" : [
      { "grade" : 90, "mean" : 100, "std" : 6 },
      { "grade" : 87, "mean" : 100, "std" : 3 },
      { "grade" : 85, "mean" : 100, "std" : 4 }
   ]
}

`hint`为更新操作指定

在 mongosh 中，创建一个 newStudents 集合，其中包含以下文档：

db.newStudents.insertMany( [
   { "_id" : 1, "student" : "Richard", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 2, "student" : "Jane", "grade" : "A", "points" : 60,  "comments1" : "well behaved", "comments2" : "fantastic student" },
   { "_id" : 3, "student" : "Ronan", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 4, "student" : "Noah", "grade" : "D", "points" : 20,  "comments1" : "needs improvement", "comments2" : null },
   { "_id" : 5, "student" : "Adam", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
   { "_id" : 6, "student" : "Henry", "grade" : "A", "points" : 86,  "comments1" : "fantastic student", "comments2" : "well behaved" }
] )

在集合上创建以下索引：

db.newStudents.createIndex( { grade: 1 } )

以下更新操作明确提示使用索引 {grade: 1 }：

db.newStudents.update(
   { points: { $lte: 20 }, grade: "F" },     // Query parameter
   { $set: { comments1: "failed class" } },  // Update document
   { multi: true, hint: { grade: 1 } }       // Options
)

注意

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

更新命令返回以下内容：

WriteResult({ "nMatched" : 3, "nUpserted" : 0, "nModified" : 3 })

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

db.newStudents.explain().update(
   { "points": { $lte: 20 }, "grade": "F" },
   { $set: { "comments1": "failed class" } },
   { multi: true, hint: { grade: 1 } }
)

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

使用以下项中的变量： `let`

版本 5.0 中的新增功能。

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

注意

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

创建集合 cakeFlavors：

db.cakeFlavors.insertMany( [
   { _id: 1, flavor: "chocolate" },
   { _id: 2, flavor: "strawberry" },
   { _id: 3, flavor: "cherry" }
] )

以下示例在 let 中定义了 targetFlavor 和 newFlavor 变量，并使用这些变量将蛋糕口味从樱桃更改为橙子：

db.cakeFlavors.update(
   { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
   [ { $set: { flavor: "$$newFlavor" } } ],
   { let : { targetFlavor: "cherry", newFlavor: "orange" } }
)

覆盖默认写关注

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

db.books.update(
   { stock: { $lte: 10 } },
   { $set: { reorder: true } },
   {
     multi: true,
     writeConcern: { w: 2, wtimeout: 5000 }
   }
)

指定排序规则。

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

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

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

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

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

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

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

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

在 mongosh 中创建名为 myColl 的集合，其中包含以下文档：

db.myColl.insertMany( [
    { _id: 1, category: "café", status: "A" },
    { _id: 2, category: "cafe", status: "a" },
    { _id: 3, category: "cafE", status: "a" }
] )

以下操作包括排序规则选项，并将 multi 设置为 true，以更新所有匹配的文档：

db.myColl.update(
   { category: "cafe" },
   { $set: { status: "Updated" } },
   {
     collation: { locale: "fr", strength: 1 },
     multi: true
   }
)

操作的写入结果返回以下文档，指示集合中的所有三个文档均已更新：

WriteResult({ "nMatched" : 3, "nUpserted" : 0, "nModified" : 3 })

操作完成后，集合包含以下文档：

{ "_id" : 1, "category" : "café", "status" : "Updated" }
{ "_id" : 2, "category" : "cafe", "status" : "Updated" }
{ "_id" : 3, "category" : "cafE", "status" : "Updated" }

WriteResult

成功结果

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

WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 })

提示

请参阅：

写关注错误

如果 db.collection.update() 方法遇到写关注错误，结果将包括 WriteResult.writeConcernError 字段：

WriteResult({
   "nMatched" : 1,
   "nUpserted" : 0,
   "nModified" : 1,
   "writeConcernError": {
     "code" : 64,
     "errmsg" : "waiting for replication timed out",
     "errInfo" : {
       "wtimeout" : true,
       "writeConcern" : {
         "w" : "majority",
         "wtimeout" : 100,
         "provenance" : "getLastErrorDefaults"
       }
   }
})

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

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

提示

另请参阅：

WriteResult.hasWriteConcernError()

与写关注无关的错误

如果 db.collection.update() 方法遇到非写关注错误，则结果将包括 WriteResult.writeError 字段：

WriteResult({
   "nMatched" : 0,
   "nUpserted" : 0,
   "nModified" : 0,
   "writeError" : {
      "code" : 7,
      "errmsg" : "could not contact primary for replica set shard-a"
   }
})

提示

另请参阅：

WriteResult.hasWriteError()

后退

db.collection.unhideIndex

来年

db.collection.updateMany

重要

已弃用的 mongosh 方法

定义

兼容性

语法

参数

返回：

访问控制

行为

$expr在带有 的更新中使用Upsert

分片集合

提示

另请参阅：

分片集合上的替换文档操作

upsert 分片集合

分片键修改

提示

缺少分片键

提示

事务

重要

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

提示

另请参阅：

写关注和事务

Oplog 条目

示例

使用更新操作符表达式（$inc 和$set ）

提示

另请参阅：

将元素推送到现有数组 ($push )

提示

另请参阅：

删除字段 ($unset )

提示

另请参阅：

更新多个文档（$update 使用multi ）

提示

另请参阅：

如果不存在匹配项，则插入新文档 (Upsert )

注意

使用替换文档进行更新或插入

使用操作符表达式进行更新或插入 ($set )

提示

另请参阅：

使用聚合管道进行更新或插入

提示

另请参阅：

将 与upsert multi结合使用（匹配）

将 与upsert multi结合使用（无匹配）

使用虚线_id 查询进行更新或插入

提示

另请参阅：

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

提示

另请参阅：

使用聚合管道进行更新

使用文档中其他字段的值修改字段

注意

提示

另请参阅：

根据当前字段值执行条件更新

注意

提示

另请参阅：

arrayFilters为数组更新操作指定

更新匹配arrayFilters 条件的元素

更新文档数组的特定元素

hint为更新操作指定

注意

使用以下项中的变量： let

注意

覆盖默认写关注

指定排序规则。

WriteResult

成功结果

提示

请参阅：

写关注错误

提示

`$expr`在带有的更新中使用`Upsert`

`upsert` 分片集合

使用更新操作符表达式（`$inc` 和`$set` ）

将元素推送到现有数组 (`$push` )

删除字段 (`$unset` )

更新多个文档（`$update` 使用`multi` ）

如果不存在匹配项，则插入新文档 (`Upsert` )

使用操作符表达式进行更新或插入 (`$set` )

将与`upsert` `multi`结合使用（匹配）

将与`upsert` `multi`结合使用（无匹配）

使用虚线`_id` 查询进行更新或插入

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

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

`hint`为更新操作指定

使用以下项中的变量： `let`