db.collection.findAndModify() (mongosh method方法)

Performance性能

Retryable writes require the findAndModify() method to copy the entire document into a special side collection for each node in a replica set before it performs the update. This can make findAndModify() an expensive operation when dealing with large documents or large replica sets.可重试写入要求findAndModify()方法在执行更新之前，将整个文档复制到副本集中每个节点的特殊侧集合中。这可能会使findAndModify()在处理大型文档或大型副本集时成为一项昂贵的操作。

fields Projection投影

The fields option takes a document in the following form:fields选项接受以下格式的文档：

{ field1: <value>, field2: <value> ... }

Upsert with Unique Index使用唯一索引进行升级

Upserts can create duplicate documents, unless there is a unique index to prevent duplicates.除非有唯一的索引来防止重复，否则Upserts可以创建重复的文档。

Consider an example where no document with the name Andy exists and multiple clients issue the following command at roughly the same time:考虑一个例子，其中不存在名为Andy的文档，多个客户端大约同时发出以下命令：

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

If all findOneAndUpdate() operations finish the query phase before any client successfully inserts data, and there is no unique index on the name field, each findOneAndUpdate() operation may result in an insert, creating multiple documents with name: Andy.如果所有findOneAndUpdate()操作都在任何客户端成功插入数据之前完成查询阶段，并且name字段上没有唯一索引，则每个findOneAndUpdate()操作可能会导致插入，从而创建多个name: Andy的文档。

A unique index on the name field ensures that only one document is created. name字段上的唯一索引可确保只创建一个文档。With a unique index in place, the multiple findOneAndUpdate() operations now exhibit the following behavior:有了一个唯一的索引，多个findOneAndUpdate()操作现在表现出以下行为：

• Exactly one findOneAndUpdate() operation will successfully insert a new document.只需执行一次findOneAndUpdate()操作，即可成功插入新文档。

• Other findOneAndUpdate() operations either update the newly-inserted document or fail due to a unique key collision.其他findOneAndUpdate()操作要么更新新插入的文档，要么由于唯一键冲突而失败。

  In order for other findOneAndUpdate() operations to update the newly-inserted document, all of the following conditions must be met:为了让其他findOneAndUpdate()操作更新新插入的文档，必须满足以下所有条件：

  • The target collection has a unique index that would cause a duplicate key error.目标集合具有唯一索引，这将导致重复键错误。
  • The update operation is not updateMany or multi is false.更新操作未updateMany或multi为false。

  • The update match condition is either:更新匹配条件为：

    • A single equality predicate. For example { "fieldA" : "valueA" }一个等式谓词。例如{ "fieldA" : "valueA" }
    • A logical AND of equality predicates. For example 等式谓词的逻辑AND。例如{ "fieldA" : "valueA", "fieldB" : "valueB" }
  • The fields in the equality predicate match the fields in the unique index key pattern.相等谓词中的字段与唯一索引键模式中的字段匹配。
  • The update operation does not modify any fields in the unique index key pattern.更新操作不会修改唯一索引键模式中的任何字段。

The following table shows examples of upsert operations that, when a key collision occurs, either result in an update or fail.下表显示了当发生键冲突时，导致更新或失败的upsert操作示例。

{ name : 1 }

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

{ name : 1 }

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

{ name : 1 }

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

Sharded Collections分片化集合

To use findAndModify on a sharded collection:要在分片集合上使用findAndModify，请执行以下操作：

• If you only target one shard, you can use a partial shard key in the query field or,如果你只针对一个分片，你可以在query字段中使用部分分片键，或者，
• You can provide an equality condition on a full shard key in the query field.您可以在query字段中为完整分片键提供相等条件。
• Starting in version 7.1, you do not need to provide the shard key or _id field in the query specification.从7.1版本开始，您不需要在query规范中提供分片键或_id字段。

Documents in a sharded collection can be missing the shard key fields. 分片集合中的文档可能缺少分片键字段。To target a document that is missing the shard key, you can use the null equality match in conjunction with another filter condition (such as on the _id field). For example:要针对缺少分片键的文档，您可以将空相等匹配与另一个筛选条件结合使用（例如在_id字段上）。例如：

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

Schema Validation模式验证

The db.collection.findAndModify() method adds support for the bypassDocumentValidation option, which lets you bypass schema validation when inserting or updating documents in a collection with validation rules.db.collection.findAndModify()方法添加了对bypassDocumentValidation选项的支持，该选项允许您在使用验证规则在集合中插入或更新文档时绕过架构验证。

Comparisons with the update Method与update方法的比较

When updating a document, db.collection.findAndModify() and the updateOne() method operate differently:更新文档时，db.collection.findAndModify()和updateOne()方法的操作不同：

• If multiple documents match the update criteria, for db.collection.findAndModify(), you can specify a sort to provide some measure of control on which document to update.如果多个文档符合更新条件，对于db.collection.findAndModify()，您可以指定一个排序，以提供对要更新的文档的某种程度的控制。

  updateOne() updates the first document that matches.更新第一个匹配的文档。

• By default, db.collection.findAndModify() returns the pre-modified version of the document. To obtain the updated document, use the new option.默认情况下，db.collection.findAndModify()返回文档的修改前版本。要获取更新的文档，请使用new选项。

  The updateOne() method returns a WriteResult() object that contains the status of the operation.updateOne()方法返回一个包含操作状态的WriteResult()对象。

  To return the updated document, use the find() method. 要返回更新的文档，请使用find()方法。However, other updates may have modified the document between your update and the document retrieval. Also, if the update modified only a single document but multiple documents matched, you will need to use additional logic to identify the updated document.但是，其他更新可能在更新和文档检索之间修改了文档。此外，如果更新仅修改了一个文档，但多个文档匹配，则需要使用其他逻辑来识别更新的文档。

When modifying a single document, both db.collection.findAndModify() and the updateOne() method atomically update the document. 修改单个文档时，db.collection.findAndModify()和updateOne()方法都会自动更新文档。See Atomicity and Transactions for more details about interactions and order of operations of these methods.有关这些方法的交互和操作顺序的更多详细信息，请参阅原子性和事务。

Transactions事务

db.collection.findAndModify() can be used inside distributed transactions.可以在分布式事务中使用。

Oplog Entries操作日志条目

If a db.collection.findAndModify() operation successfully finds and modifies a document, the operation adds an entry on the oplog (operations log). 如果db.collection.findAndModify()操作成功找到并修改了文档，则该操作会在oplog（操作日志）上添加一个条目。If the operation fails or does not find a document to modify, the operation does not add an entry on the oplog.如果操作失败或找不到要修改的文档，则操作不会在oplog上添加条目。

Write Concern Errors写入关注错误

In MongoDB versions earlier than 6.0, if the findAndModify command is run on a sharded cluster, mongos discards the writeConcernError document if the shard response contains an error. 在MongoDB 6.0之前的版本中，如果在分片集群上运行findAndModify命令，如果分片响应包含错误，mongos将丢弃writeConcernError文档。In MongoDB 6.0 and later, mongos returns writeConcernError.在MongoDB 6.0及更高版本中，mongos返回writeConcernError。

Update and Return更新和返回

The following method updates and returns an existing document in the people collection where the document matches the query criteria:以下方法更新并返回人员集合中与查询条件匹配的现有文档：

db.people.findAndModify({
    query: { name: "Tom", state: "active", rating: { $gt: 10 } },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } }
})

This method performs the following actions:此方法执行以下操作：

1. The query finds a document in the people collection where the name field has the value Tom, the state field has the value active and the rating field has a value greater than 10.query在people集合中找到一个文档，其中name字段的值为Tom，state字段的值是active，rating字段的值大于10。
2. The sort orders the results of the query in ascending order. If multiple documents meet the query condition, the method will select for modification the first document as ordered by this sort.sort按升序对查询结果进行排序。如果多张单据符合query条件，则该方法将按此排序选择第一张单据进行修改。
3. The update increments the value of the score field by 1.更新将score字段的值递增1。

4. The method returns the original (i.e. pre-modification) document selected for this update:该方法返回为此更新选择的原始（即修改前）文档：

   {
     "_id" : ObjectId("50f1e2c99beb36a0f45c6453"),
     "name" : "Tom",
     "state" : "active",
     "rating" : 100,
     "score" : 5
   }

   To return the updated document, add the new:true option to the method.要返回更新的文档，请在方法中添加new:true选项。

   If no document matched the query condition, the method returns null.如果没有符合query条件的文档，则该方法返回null。

Upsert

The following method includes the upsert: true option for the update operation to either update a matching document or, if no matching document exists, create a new document:以下方法包括update操作的upsert: true选项，用于更新匹配的文档，或者在不存在匹配文档的情况下创建新文档：

db.people.findAndModify({
    query: { name: "Gus", state: "active", rating: 100 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true
})

If the method finds a matching document, the method performs an update.如果该方法找到匹配的文档，则该方法将执行更新。

If the method does not find a matching document, the method creates a new document. Because the method included the sort option, it returns an empty document { } as the original (pre-modification) document:如果该方法找不到匹配的文档，则该方法将创建一个新文档。因为该方法包含sort选项，所以它返回一个空文档{ }作为原始（修改前）文档：

{ }

If the method did not include a sort option, the method returns null.如果该方法不包括sort选项，则该方法返回null。

null

Return New Document返回新文档

The following method includes both the upsert: true option and the new:true option. 以下方法包括upsert: true选项和new:true选项。The method either updates a matching document and returns the updated document or, if no matching document exists, inserts a document and returns the newly inserted document in the value field.该方法更新匹配的文档并返回更新后的文档，或者如果不存在匹配的文档，则插入文档并在value字段中返回新插入的文档。

In the following example, no document in the people collection matches the query condition:在以下示例中，people集合中没有文档符合query条件：

db.people.findAndModify({
    query: { name: "Pascal", state: "active", rating: 25 },
    sort: { rating: 1 },
    update: { $inc: { score: 1 } },
    upsert: true,
    new: true
})

The method returns the newly inserted document:该方法返回新插入的文档：

{
   "_id" : ObjectId("50f49ad6444c11ac2448a5d6"),
   "name" : "Pascal",
   "rating" : 25,
   "score" : 1,
   "state" : "active"
}

Sort and Remove排序和删除

By including a sort specification on the rating field, the following example removes from the people collection a single document with the state value of active and the lowest rating among the matching documents:通过在rating字段中包含sort规范，以下示例从people集合中删除了state值为active且在匹配文档中rating最低的单个文档：

db.people.findAndModify(
   {
     query: { state: "active" },
     sort: { rating: 1 },
     remove: true
   }
)

The method returns the deleted document:该方法返回已删除的文档：

{
   "_id" : ObjectId("52fba867ab5fdca1299674ad"),
   "name" : "XYZ123",
   "score" : 1,
   "state" : "active",
   "rating" : 3
}

Specify Collation指定排序规则

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音标记的规则。

A collection myColl has the following documents:myColl集合有以下文件：

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

The following operation includes the collation option:以下操作包括排序规则选项：

db.myColl.findAndModify({
    query: { category: "cafe", status: "a" },
    sort: { category: 1 },
    update: { $set: { status: "Updated" } },
    collation: { locale: "fr", strength: 1 }
});

The operation returns the following document:该操作返回以下文档：

{ "_id" : 1, "category" : "café", "status" : "A" }

Specify arrayFilters for an Array Update Operations为数组更新操作指定arrayFilters

When updating an array field, you can specify arrayFilters that determine which array elements to update.更新数组字段时，可以指定arrayFilters来确定要更新的数组元素。

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

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

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

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 }
      ]
   }
] )

db.students2.findAndModify({
   query: { _id : 1 },
   update: { $set: { "grades.$[elem].mean" : 100 } },
   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" : 75, "std" : 6 },
      { "grade" : 87, "mean" : 90, "std" : 3 },
      { "grade" : 85, "mean" : 85, "std" : 4 }
   ]
}

Use an Aggregation Pipeline for Updates使用聚合管道进行更新

db.collection.findAndModify() can accept an aggregation pipeline for the update. The pipeline can consist of the following stages:可以接受更新的聚合管道。管道可包括以下阶段：

• $addFields and its alias 及其别名$set
• $project and its alias 及其别名$unset
• $replaceRoot and its alias 及其别名$replaceWith

Using the aggregation pipeline allows for a more expressive update statement, such as expressing conditional updates based on current field values or updating one field using the value of another field(s).使用聚合管道允许更具表现力的更新语句，例如基于当前字段值表示条件更新，或使用另一个字段的值更新一个字段。

For example, create a collection students2 with the following documents:例如，使用以下文档创建一个集合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 }
      ]
   }
] )

The following operation finds a document where the _id field equals 1 and uses an aggregation pipeline to calculate a new field total from the grades field:以下操作查找_id字段等于1的文档，并使用聚合管道从grades字段计算新的字段total：

db.students2.findAndModify( {
   query: {  "_id" : 1 },
   update: [ { $set: { "total" : { $sum: "$grades.grade" } } } ],  // The $set stage is an alias for ``$addFields`` stage
   new: true
} )

The operation returns the updated document:该操作返回更新的文档：

{
   "_id" : 1,
   "grades" : [ { "grade" : 80, "mean" : 75, "std" : 6 }, { "grade" : 85, "mean" : 90, "std" : 4 }, { "grade" : 85, "mean" : 85, "std" : 6 } ],
   "total" : 250
}

Use Variables in let在let中使用变量

To define variables that you can access elsewhere in the command, use the let option.要定义可以在命令的其他地方访问的变量，请使用let选项。

Create a collection cakeFlavors:创建一个系列cakeFlavors：

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

The following example defines a targetFlavor variable in let and uses the variable to change the cake flavor from cherry to orange:以下示例在let中定义了targetFlavor变量，并使用该变量将蛋糕风味从樱桃味更改为橙色：

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

User Roles and Document Updates用户角色和文档更新

Starting in MongoDB 7.0, you can use the new USER_ROLES system variable to return user roles.从MongoDB 7.0开始，您可以使用新的USER_ROLES系统变量返回用户角色。

The example in this section shows updates to fields in a collection containing medical information. The example reads the current user roles from the USER_ROLES system variable and only performs the updates if the user has a specific role.本节中的示例显示了包含医疗信息的集合中字段的更新。该示例从USER_ROLES系统变量读取当前用户角色，并且仅在用户具有特定角色时执行更新。

To use a system variable, add $$ to the start of the variable name. Specify the USER_ROLES system variable as $$USER_ROLES.要使用系统变量，请在变量名的开头添加$$。将USER_ROLES系统变量指定为$$USER_ROLES。

The example creates these users:该示例创建了以下用户：

• James with a Billing role.具有Billing角色。
• Michelle with a Provider role.具有Provider角色

Perform the following steps to create the roles, users, and collection:执行以下步骤以创建角色、用户和集合：

db.createRole( { role: "Billing", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )
db.createRole( { role: "Provider", privileges: [ { resource: { db: "test",
   collection: "medicalView" }, actions: [ "find" ] } ], roles: [ ] } )

db.createUser( {
   user: "James",
   pwd: "js008",
   roles: [
      { role: "Billing", db: "test" }
   ]
} )

db.createUser( {
   user: "Michelle",
   pwd: "me009",
   roles: [
      { role: "Provider", db: "test" }
   ]
} )

db.medical.insertMany( [
   {
      _id: 0,
      patientName: "Jack Jones",
      diagnosisCode: "CAS 17",
      creditCard: "1234-5678-9012-3456"
   },
   {
      _id: 1,
      patientName: "Mary Smith",
      diagnosisCode: "ACH 01",
      creditCard: "6541-7534-9637-3456"
   }
] )

Log in as as Michelle, who has the Provider role, and perform an update:以Michelle（具有Provider角色）的身份登录，并执行更新：

db.auth( "Michelle", "me009" )

// Attempt to find and modify document
db.medical.findAndModify( {
   query:
      { $and: [
         {
            // Only update the document for Mary Smith
            patientName: { $eq: "Mary Smith" }
         },
         {
            // User must have the Provider role to perform the update
            $expr: { $ne: [ {
               $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ]
            }, [] ] }
         }
      ]
   },
   // Update document
   update: {
      patientName: "Mary Smith",
      diagnosisCode: "ACH 03",
      creditCard: "6541-7534-9637-3456"
   }
} )

The previous example uses $setIntersection to return documents where the intersection between the "Provider" string and the user roles from $$USER_ROLES.role is not empty. 前面的示例使用$setIntersection返回文档，其中"Provider"字符串与$$USER_ROLES.role中的用户角色之间的交集不为空。Michelle has the Provider role, so the update is performed.Michelle具有Provider角色，因此执行更新。

Next, log in as as James, who does not have the Provider role, and attempt to perform the same update:接下来，以没有Provider角色的James身份登录，并尝试执行相同的更新：

db.auth( "James", "js008" )

// Attempt to find and modify document
db.medical.findAndModify( {
   query:
      { $and: [
         {
            // Only update the document for Mary Smith
            patientName: { $eq: "Mary Smith" }
         },
         {
            // User must have the Provider role to perform the update
            $expr: { $ne: [ {
               $setIntersection: [ [ "Provider" ], "$$USER_ROLES.role" ]
            }, [] ] }
         }
      ]
   },
   // Update document
   update: {
      patientName: "Mary Smith",
      diagnosisCode: "ACH 03",
      creditCard: "6541-7534-9637-3456"
   }
} )

The previous example does not update any documents.前面的示例不会更新任何文档。