db.collection.findAndModify（）

定义¶

db.collection.findAndModify（文件）¶

mongo 壳法

此页面记录了mongoshell方法，并且 没有引用MongoDB Node.js驱动程序（或任何其他驱动程序）方法。对于相应的MongoDB驱动程序API，请改为参考您特定的 MongoDB驱动程序文档。

修改并返回单个文档。默认情况下，返回的文档不包括对更新所做的修改。要返回对更新进行了修改的文档，请使用new选项。该findAndModify() 方法是findAndModify 命令周围的shell帮手。

该findAndModify()方法具有以下形式：

复制

db.collection.findAndModify({
    query: <document>,
    sort: <document>,
    remove: <boolean>,
    update: <document or aggregation pipeline>, // Changed in MongoDB 4.2
    new: <boolean>,
    fields: <document>,
    upsert: <boolean>,
    bypassDocumentValidation: <boolean>,
    writeConcern: <document>,
    collation: <document>,
    arrayFilters: [ <filterdocument1>, ... ]
});

该db.collection.findAndModify()方法采用带有以下嵌入式文档字段的文档参数：

参数	类型	描述
query	文献	可选的。修改的选择标准。该query字段采用相同的查询选择器如在所使用的db.collection.find()方法。尽管查询可能匹配多个文档，但只会选择一个文档进行修改。db.collection.findAndModify() 如果未指定，则默认为空文档。 从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果查询参数不是文档，则操作错误。
sort	文献	可选的。确定如果查询选择多个文档，则操作将修改哪个文档。db.collection.findAndModify()按照此参数指定的排序顺序修改第一个文档。 从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果sort参数不是文档，则操作会出错。
remove	布尔值	必须指定remove或update字段。删除在query字段中指定的文档。设置此项以true 删除选定的文档。默认值为false。
update	文件或阵列	必须指定remove或update字段。执行所选文档的更新。 如果传递带有update运算符表达式的文档，则db.collection.findAndModify()执行指定的修改。 如果通过了替换文件，则执行替换。{ <field1>: <value1>, ...}db.collection.findAndModify() 在MongoDB中4.2开始，如果通过一个汇聚管道 ， 修改每个管道中的文档。管道可以包括以下阶段：[ <stage1>, <stage2>, ... ]db.collection.findAndModify() $addFields 及其别名 $set $project 及其别名 $unset $replaceRoot及其别名$replaceWith。
new	布尔值	可选的。当为时true，返回修改后的文档而不是原始文档。该db.collection.findAndModify()方法忽略 操作new选项remove。默认值为false。
fields	文献	可选的。要返回的字段子集。该fields文档使用来指定包含一个字段1，例如：。见投影。fields: { <field1>: 1, <field2>: 1, ... } 从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果fields参数不是文档，则操作错误。
upsert	布尔值	可选的。与update现场配合使用。 当true，findAndModify()要么： 如果没有文档与匹配，则创建一个新文档query。有关更多详细信息，请参见upsert行为。 更新与匹配的单个文档query。 为避免多次更新，请确保query字段被唯一索引。 默认为false。
bypassDocumentValidation	布尔值	可选的。允许db.collection.findAndModify在操作过程中绕过文档验证。这使您可以更新不满足验证要求的文档。 3.2版中的新功能。
writeConcern	文献	可选的。表达书面关切的文件。省略使用默认的写关注。 如果在事务中运行，则不要为操作明确设置写关注点。要对事务使用写关注，请参见 事务和写关注。 3.2版中的新功能。
maxTimeMS	整数	可选的。指定用于处理操作的时间限制（以毫秒为单位）。
collation	文献	可选的。 指定 用于操作的排序规则。 归类允许用户为字符串比较指定特定于语言的规则，例如字母大写和重音符号的规则。 排序规则选项具有以下语法： 复制 collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> } 指定排序规则时，该locale字段为必填字段；所有其他排序规则字段都是可选的。有关字段的说明，请参见整理文档。 如果未指定排序规则，但是集合具有默认排序规则（请参阅参考资料db.createCollection()），则该操作将使用为集合指定的排序规则。 如果没有为集合或操作指定排序规则，则MongoDB使用先前版本中使用的简单二进制比较进行字符串比较。 您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果对排序执行查找，则不能对查找使用一种排序规则，而对排序使用另一种排序规则。 3.4版的新功能。
arrayFilters	数组	可选的。筛选器文档数组，用于确定要对数组字段进行更新操作要修改的数组元素。 在更新文档中，使用$[<identifier>]过滤后的位置运算符定义一个标识符，然后在数组过滤器文档中引用该标识符。如果该标识符未包含在更新文档中，则不能具有标识符的数组过滤器文档。 注意 在<identifier>必须以小写字母开头，并且只包含字母数字字符。 您可以在更新文档中多次包含相同的标识符；但是，对于$[identifier]更新文档中的每个不同的标识符（），必须精确地指定一个 对应的数组过滤器文档。也就是说，您不能为同一标识符指定多个数组过滤器文档。例如，如果update语句包含标识符x （可能多次），则不能为以下内容指定以下内容 arrayFilters：包括2个单独的过滤器文档x： // 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 不适用于使用聚合管道的更新。 3.6版的新功能。

返回数据¶

对于删除操作，如果查询与文档匹配，则 findAndModify()返回删除的文档。如果查询与要删除的文档不匹配，则 findAndModify()返回null。

对于更新操作，findAndModify()返回以下之一：

• 如果new参数未设置或为false：
  • 如果查询与文档匹配，则为修改前文档；
  • 否则，null。
• 如果new是true：
  • 如果查询返回匹配项，则修改后的文档；
  • 如果没有文档匹配查询，则插入文档；upsert: true
  • 否则，null。

行为¶

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

例子¶

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

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

{ }

null

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

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

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

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

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

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

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

db.students.insert([
   { "_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 } } ]
})