MongoDB\Collection::replaceOne()
定义
MongoDB\Collection::replaceOne()
最多替换一个与筛选条件匹配的文档。 如果有多个文档符合筛选条件,则仅替换第一个匹配的文档。
function replaceOne( array|object $filter, array|object $replacement, array $options = [] ): MongoDB\UpdateResult
参数
$filter
: array|object- 指定要替换的文档的筛选条件。
$replacement
: array|object- 替换文档。
$options
: array指定所需选项的数组。
名称类型说明bypassDocumentValidation
布尔
如果为
true
,则允许写入操作规避文档级验证。默认为false
。编解码器
MongoDB\Codec\DocumentCodec
排序规则
数组|对象
comment
混合
提示
字符串|数组|对象
要使用的索引。将索引名称指定为字符串或将索引键模式指定为文档。如果指定,查询系统将只考虑使用提示索引的计划。
自 MongoDB 4.2 起此选项可用,如果为旧服务器版本指定,则会在执行时导致异常。
1.6 版本中的新增功能。
let
数组|对象
参数名称和值的映射。值必须是常量或不引用文档字段的封闭表达式。然后可以在聚合表达式上下文中将参数作为变量进行访问(例如
$$var
)。5.0 之前的服务器版本不支持此功能,如果使用,将导致执行时出现异常。
1.13 版本中的新增功能。
会话
与操作相关联的客户端会话。
1.3 版本中的新增功能。
sort
数组|对象
匹配文档排序的排序规范。设置此选项可在服务器执行替换操作之前对匹配的文档应用顺序。
1.21版本新增。
更新插入
布尔
如果设置为
true
,则在没有文档符合查询条件时创建一个新文档。默认值为false
,在未找到匹配项时不插入新文档。writeConcern
Return Values
一个MongoDB\UpdateResult
对象,其中封装了 MongoDB\Driver\WriteResult 对象。
错误/异常
MongoDB\Exception\UnsupportedException
,如果所选服务器使用了选项但不支持选项(例如collation
、readConcern
、writeConcern
)。
MongoDB\Exception\InvalidArgumentException
用于与参数或选项解析相关的错误。
MongoDB\Driver\Exception\BulkWriteException 与写入操作相关的错误。用户应检查 getWriteResult() 返回的值 以确定错误的性质。
MongoDB\ 驱动程序\Exception\RuntimeException 对于扩展级别的其他错误(例如连接错误)。
行为
在评估查询条件时,MongoDB 会根据自己 的 比较规则来BSON types 比较类型和值,这不同于 的PHP 比较 和 类型杂技 规则。匹配特殊BSON类型时,查询条件应使用相应的 BSON类 在扩展(例如使用 MongoDB\ BSON\ObjectId 以匹配 ObjectId )。
如果 MongoDB\Driver\Exception\BulkWriteException 抛出,用户应调用 getWriteResult() 并检查返回的 MongoDB\Driver\WriteResult 对象以确定错误的性质。
例如,写入操作可能已成功应用于主服务器,但未能满足写关注(例如复制时间太长)。或者,写入操作可能完全失败(例如唯一键冲突)。
例子
以下示例将文档替换为数据库test
中collectionrestaurants
中"40356068"
的restaurant_id
:
$collection = (new MongoDB\Client)->test->restaurants; $updateResult = $collection->replaceOne( [ 'restaurant_id' => '40356068' ], [ 'name' => 'New Restaurant', 'restaurant_id' => '99988877', 'borough' => 'Queens', 'cuisine' => 'Cafe', 'grades' => [], ] ); printf("Matched %d document(s)\n", $updateResult->getMatchedCount()); printf("Modified %d document(s)\n", $updateResult->getModifiedCount());
而输出将类似如下所示:
Matched 1 document(s) Modified 1 document(s)