db.collection.findOneAndReplace（）

MongoDB 中文手册

参考 > 参考 > mongo Shell方法 > 收集方法 > db.collection.findOneAndReplace（）

在本页面

定义
句法
行为
例子

定义¶

db.collection.findOneAndReplace（filter，replace，options ）¶: mongo 壳法

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

3.2版中的新功能。

根据指定的过滤器替换单个文档。

语法¶

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

复制

db.collection.findOneAndReplace(
   <filter>,
   <replacement>,
   {
     projection: <document>,
     sort: <document>,
     maxTimeMS: <number>,
     upsert: <boolean>,
     returnNewDocument: <boolean>,
     collation: <document>
   }
)

参数和选项¶

该findOneAndReplace()方法采用以下参数和选项：

参数	类型	描述
过滤	文献	更新的选择标准。提供与方法中相同的查询选择器 `find()`。指定一个空文档以替换集合中返回的第一个文档。`{ }` 如果未指定，则默认为空文档。从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果查询参数不是文档，则操作错误。
替代	文献	替换文件。不能包含更新运算符。该`<replacement>`文档不能指定`_id`与替换文档不同的值。
投影	文献	可选的。要返回的字段子集。要返回匹配文档中的所有字段，请省略此参数。从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果projection参数不是文档，则操作会出错。
分类	文献	可选的。指定与匹配的文档的排序顺序`filter`。从MongoDB 4.2（和4.0.12 +，3.6.14 +和3.4.23+）开始，如果sort参数不是文档，则操作会出错。请参阅`cursor.sort()`。
`maxTimeMS`	数	可选的。指定必须在其中完成操作的时间限制（以毫秒为单位）。如果超出限制，则会引发错误。
上升	布尔值	可选的。当`true`，`findOneAndReplace()`要么： `replacement`如果没有文档与参数匹配，则从参数插入文档`filter`。`null`插入新文档后返回，除非`returnNewDocument`是`true`。将与匹配的文档替换`filter`为该`replacement`文档。 `_id`如果`filter`或`replacement`文档中未指定，则MongoDB会将字段添加到替换文档中。如果`_id`两者都存在，则值必须相等。为避免多次更新，请确保`query`字段被唯一索引。默认为`false`。
returnNewDocument	布尔值	可选的。如果为`true`，则返回替换文档而不是原始文档。默认为`false`。
校对	文献	可选的。指定用于操作的排序规则。归类允许用户为字符串比较指定特定于语言的规则，例如字母大写和重音符号的规则。排序规则选项具有以下语法：复制 collation: { locale: <string>, caseLevel: <boolean>, caseFirst: <string>, strength: <int>, numericOrdering: <boolean>, alternate: <string>, maxVariable: <string>, backwards: <boolean> } 指定排序规则时，该`locale`字段为必填字段；所有其他排序规则字段都是可选的。有关字段的说明，请参见整理文档。如果未指定排序规则，但是集合具有默认排序规则（请参阅参考资料`db.createCollection()`），则该操作将使用为集合指定的排序规则。如果没有为集合或操作指定排序规则，则MongoDB使用先前版本中使用的简单二进制比较进行字符串比较。您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果对排序执行查找，则不能对查找使用一种排序规则，而对排序使用另一种排序规则。 3.4版的新功能。

返回¶

返回原始文档，或者如果替换文档，则返回returnNewDocument：true。

行为¶

单证相符¶

db.collection.findOneAndReplace()替换集合中与匹配的第一个匹配文档filter。该sort参数可用于影响修改哪个文档。

投影¶

该projection参数采用以下格式的文档：

复制

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

该<boolean>值可以是以下任意值：

1或true包含该字段。_id即使未在projection参数中明确说明该方法，该方法也会返回该字段。
0或false排除该字段。可以在任何字段（包括）上使用_id。

分片集合¶

要db.collection.findOneAndReplace()在分片集合上使用，查询过滤器必须在分片键上包含相等条件。

碎片键修改¶

从MongoDB 4.2开始，除非分片键字段是不可变_id字段，否则您可以更新文档的分片键值。有关更新分片键的详细信息，请参阅“ 更改文档的分片键值”。

在MongoDB 4.2之前，文档的分片键字段值是不可变的。

交易¶

db.collection.findOneAndReplace()可以在多文档交易中使用。

如果该操作导致upsert，则该集合必须已经存在。

如果在事务中运行，则不要为操作明确设置写关注点。要对事务使用写关注，请参见事务和写关注。

重要

在大多数情况下，与单文档写入相比，多文档事务产生的性能成本更高，并且多文档事务的可用性不应代替有效的架构设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）对于您的数据和用例将继续是最佳的。也就是说，在许多情况下，对数据进行适当的建模将最大程度地减少对多文档交易的需求。

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

例子¶

替换文件¶

scores使用以下文档创建样本集合：

复制

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
]);

以下操作查找score小于的文档20000并将其替换：

复制

db.scores.findOneAndReplace(
   { "score" : { $lt : 20000 } },
   { "team" : "Observant Badgers", "score" : 20000 }
)

该操作返回已替换的原始文档：

复制

{ "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 }

如果returnNewDocument为true，则该操作将返回替换文档。

尽管多个文档符合过滤条件，但 db.collection.findOneAndReplace仅替换一个文档。

排序和替换文件¶

scores使用以下文档创建样本集合：

复制

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
]);

通过在字段上包括升序排序score，以下示例将替换与筛选器匹配的那些文档中得分最低的文档：

复制

db.scores.findOneAndReplace(
   { "score" : { $lt : 20000 } },
   { "team" : "Observant Badgers", "score" : 20000 },
   { sort: { "score" : 1 } }
)

该操作返回已替换的原始文档：

复制

{ "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 }

有关此命令的未排序结果，请参阅替换文档。

退货文档中的项目特定字段¶

scores使用以下文档创建样本集合：

复制

db.scores.insertMany([
   { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 },
   { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 },
   { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 },
   { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 },
   { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 }
])

以下操作使用投影仅team在返回的文档中显示该字段：

复制

db.scores.findOneAndReplace(
   { "score" : { $lt : 22250 } },
   { "team" : "Therapeutic Hamsters", "score" : 22250 },
   { sort : { "score" : 1 }, projection: { "_id" : 0, "team" : 1 } }
)

该操作仅使用以下字段返回原始文档team：

复制

{ "team" : "Cuddly Zebras" }

将文档替换为时间限制¶

以下操作将完成时间设置为5毫秒：

复制

try {
   db.scores.findOneAndReplace(
      { "score" : { $gt : 25000 } },
      { "team" : "Emphatic Rhinos", "score" : 25010 },
      { maxTimeMS: 5 }
   );
} catch(e){
   print(e);
}

如果操作超过时间限制，则返回：

复制

Error: findAndModifyFailed failed: { "ok" : 0, "errmsg" : "operation exceeded time limit", "code" : 50 }

用Upsert替换文档¶

如果没有文档与过滤器匹配，以下操作将使用upsert字段插入替换文档：

复制

try {
   db.scores.findOneAndReplace(
      { "team" : "Fortified Lobsters" },
      { "_id" : 6019, "team" : "Fortified Lobsters" , "score" : 32000},
      { upsert : true, returnNewDocument: true }
   );
} catch (e){
   print(e);
}

该操作返回以下内容：

复制

{
   "_id" : 6019,
   "team" : "Fortified Lobsters",
   "score" : 32000
}

如果returnNewDocument为假，操作将返回，null因为没有原始文档要返回。

指定归类¶

3.4版的新功能。

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

myColl使用以下文档创建样本集合：

复制

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

以下操作包括排序规则选项：

复制

db.myColl.findOneAndReplace(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }
);

该操作返回以下文档：

复制

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