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	使用类型编解码器对数据进行编码，用于对文档进行编码或解码。此选项与 `typeMap` 选项互斥。默认为集合的编解码器。默认 `codec` 选项的继承优先于 `typeMap` 选项的继承。 1.17版本新增。
排序规则	数组\|对象	Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the `locale` field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document. 如果未指定排序规则但集合具有默认排序规则，则操作将使用为集合指定的排序规则。如果没有为集合或操作指定排序规则，MongoDB 将使用先前版本中用于字符串比较的简单二进制比较。
comment	混合	使用户可以指定任意注释来帮助通过数据库分析器、currentOp 输出和日志来跟踪操作。自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。 1.13版本新增。
提示	字符串\|数组\|对象	要使用的索引。将索引名称指定为字符串或将索引键模式指定为文档。如果指定，查询系统将只考虑使用提示索引的计划。自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。 1.6版本新增。
let	数组\|对象	参数名称和值的映射。值必须是常量或不引用文档字段的封闭表达式。然后可以在聚合表达式上下文中将参数作为变量进行访问（例如 `$$var`）。 5.0 之前的服务器版本不支持此功能，如果使用，将导致执行时出现异常。 1.13版本新增。
会话	MongoDB\Driver\Session	与操作相关联的客户端会话。 1.3版本新增。
sort	数组\|对象	匹配文档排序的排序规范。设置此选项可在服务器执行替换操作之前对匹配的文档应用顺序。 1.21版本新增。
更新插入	布尔	如果设置为 `true`，则在没有文档符合查询条件时创建一个新文档。默认值为 `false`，在未找到匹配项时不插入新文档。
writeConcern	MongoDB\Driver\WriteConcern	Write concern to use for the operation. Defaults to the collection's write concern. 无法将单个操作的写关注（write concern）指定为ACID 事务的一部分。相反，请在启动ACID 事务时设立`writeConcern` 选项。

Return Values

一个MongoDB\UpdateResult对象，其中封装了MongoDB\驱动程序\WriteResult对象。

错误/异常

MongoDB\Exception\UnsupportedException，如果所选服务器使用了选项但不支持选项（例如collation、readConcern、writeConcern）。

MongoDB\Exception\InvalidArgumentException 用于与参数或选项解析相关的错误。

MongoDB\ 驱动程序\Exception\BulkWriteException 以了解与写入操作相关的错误。用户应检查 getWriteResult() 返回的值，以确定错误的性质。

MongoDB\ 驱动程序\Exception\RuntimeException 用于扩展级别的其他错误（例如连接错误）。

行为

在评估查询条件时， MongoDB会根据自己的BSON 类型比较规则来比较类型和值，这与 PHP 的比较和类型规则不同。匹配特殊BSON类型时，查询条件应使用扩展中相应的BSON类（例如使用MongoDB\BSON\ObjectId来匹配ObjectId）。

如果引发MongoDB\ 驱动程序\Exception\BulkWriteException，则用户应调用getWriteResult()并检查返回的MongoDB\ 驱动程序\WriteResult对象，以确定错误的性质。

例如，写入操作可能已成功应用于主服务器，但未能满足写关注（例如复制时间太长）。或者，写入操作可能完全失败（例如唯一键冲突）。

例子

以下示例将文档替换为数据库test中collectionrestaurants中"40356068"的restaurant_id ：

<?php
$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)

另请参阅

MongoDB\Collection::updateMany()
MongoDB\Collection::updateOne()
MongoDB\Collection::bulkWrite()
替换文档
update command reference in the MongoDB manual