参考 > 参考 > mongo Shell方法 > 收集方法 > db.collection.replaceOne()
db.collection.
replaceOne
(filter,replace,options )¶mongo
壳法
此页面记录了mongo
shell方法,并且
没有引用MongoDB Node.js驱动程序(或任何其他驱动程序)方法。对于相应的MongoDB驱动程序API,请改为参考您特定的
MongoDB驱动程序文档。
3.2版中的新功能。
根据过滤器替换集合中的单个文档。
该replaceOne()
方法具有以下形式:
该replaceOne()
方法采用以下参数:
参数 | 类型 | 描述 |
---|---|---|
过滤 | 文献 |
指定一个空文档以替换集合中返回的第一个文档。 |
replacement |
文献 | 替换文件。 不能包含 更新运算符。 |
upsert |
布尔值 | 可选的。当
为避免多次更新,请确保 默认为 |
writeConcern |
文献 | 可选的。表达书面关切的文件。省略使用默认的写关注。 如果在事务中运行,则不要为操作明确设置写关注点。要对事务使用写关注,请参见 事务和写关注。 |
collation |
文献 | 可选的。 指定 用于操作的排序规则。 归类允许用户为字符串比较指定特定于语言的规则,例如字母大写和重音符号的规则。 排序规则选项具有以下语法: 指定排序规则时,该 如果未指定排序规则,但是集合具有默认排序规则(请参阅参考资料 如果没有为集合或操作指定排序规则,则MongoDB使用先前版本中使用的简单二进制比较进行字符串比较。 您不能为一个操作指定多个排序规则。例如,您不能为每个字段指定不同的排序规则,或者如果对排序执行查找,则不能对查找使用一种排序规则,而对排序使用另一种排序规则。 3.4版的新功能。 |
暗示 | 文献 |
该选项可以采用索引规范文档或索引名称字符串。 如果指定的索引不存在,则操作错误。 有关示例,请参阅为replaceOne指定提示。 4.2.1版中的新功能。 |
返回值: | 包含以下内容的文档:
|
---|
replaceOne()
替换匹配的集合中的第一个匹配的文件filter
,使用该replacement
文件。
upsert
¶如果和没有文档匹配,则
根据文档创建一个新文档。upsert: true
filter
db.collection.replaceOne()
replacement
如果在分片集合上指定,则必须在中包含完整的分片密钥。有关分片集合的其他
行为,请参见分片集合。upsert: true
filter
db.collection.replaceOne()
请参阅用Upsert替换。
如果替换操作更改了文档大小,则该操作将失败。
从MongoDB 4.2开始,首先db.collection.replaceOne()
尝试使用查询过滤器定位单个分片。如果该操作无法通过查询过滤器定位到单个分片,则它将尝试以替换文档定位。
在早期版本中,该操作尝试使用替换文档作为目标。
如果替换分片集合中的文档,则替换文档必须包含分片键。附加要求适用于分 片集合和分片 密钥修改上的更新。
upsert
在分片集合上¶从MongoDB 4.2开始,对于db.collection.replaceOne()
包含分片集合并在分片集合上的操作,必须在中包含完整的分片键。upsert: true
filter
从MongoDB 4.2开始,除非分片键字段是不可变_id
字段,否则您可以更新文档的分片键值。有关更新分片键的详细信息,请参阅“ 更改文档的分片键值”。
在MongoDB 4.2之前,文档的分片键字段值是不可变的。
要用于db.collection.replaceOne()
更新分片键:
db.collection.replaceOne()
可以在多文档交易中使用。
如果该操作导致upsert,则该集合必须已经存在。
如果在事务中运行,则不要为操作明确设置写关注点。要对事务使用写关注,请参见 事务和写关注。
重要
在大多数情况下,与单文档写入相比,多文档事务产生的性能成本更高,并且多文档事务的可用性不应代替有效的架构设计。在许多情况下, 非规范化数据模型(嵌入式文档和数组)对于您的数据和用例将继续是最佳的。也就是说,在许多情况下,对数据进行适当的建模将最大程度地减少对多文档交易的需求。
有关其他事务使用方面的注意事项(例如运行时限制和oplog大小限制),另请参见 生产注意事项。
该restaurant
集合包含以下文档:
以下操作替换单个文档,其中
:name: "Central Perk Cafe"
该操作返回:
如果未找到匹配项,则该操作返回:
如果找不到匹配项,则设置将插入文档。请参阅
替换为Upsertupsert: true
该restaurant
集合包含以下文档:
下面的操作尝试,以取代该文件
,用:name : "Pizza Rat's Pizzaria"
upsert : true
由于文档是基于文档插入的
。该操作返回:upsert : true
replacement
现在,该集合包含以下文档:
hint
用于replaceOne
¶4.2.1版中的新功能。
members
使用以下文档创建样本集合:
在集合上创建以下索引:
以下更新操作明确暗示要使用索引:{
status: 1 }
注意
如果指定的索引不存在,则操作错误。
该操作返回以下内容:
要查看使用的索引,可以使用$indexStats
管道: