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`。
codec	MongoDB\Codec\DocumentCodec	用于编码或解码文档的codec。此选项与 `typeMap` 选项互斥。默认为集合的 codec。默认 `codec` 选项的继承优先于 `typeMap` 选项。新增加在版本1.17.
collation	数组\|对象	Collation 允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。指定 collation 时，`locale` 字段是必需的；所有其他 collation 字段都是可选的。有关字段的说明，请参阅 Collation 文档。如果未指定 collation，但集合有一个默认 collation，则操作使用集合指定的 collation。如果集合或操作未指定 collation，MongoDB 将使用先前版本中用于字符串比较的简单二进制比较。
comment	混合型	允许用户指定任意注释，以帮助通过数据库分析器、currentOp 输出和日志跟踪操作。此选项从 MongoDB 4.4 开始可用，如果为旧服务器版本指定，将在执行时引发异常。新增加在版本1.13.
hint	字符串\|数组\|对象	要使用的索引。指定索引名称作为字符串或索引键模式作为文档。如果指定，则查询系统将仅考虑使用提示索引的计划。此选项从 MongoDB 4.2 开始可用，如果为旧服务器版本指定，将在执行时引发异常。新增加在版本1.6.
let	数组\|对象	参数名称和值的映射。值必须是常数或封闭表达式，不引用文档字段。然后可以在聚合表达式上下文中访问参数作为变量（例如 `$$var`）。不支持 5.0 之前的服务器版本，如果使用将引发异常。新增加在版本1.13.
session	MongoDB\Driver\Session	与操作关联的客户端会话。新增加在版本1.3.
upsert	布尔型	如果设置为 `true`，则在没有文档与查询标准匹配时创建新文档。默认值为 `false`，这意味着如果没有找到匹配项则不会插入新文档。
writeConcern	MongoDB\Driver\WriteConcern	用于操作的写关注。默认为集合的写关注。在事务中无法为单个操作指定写关注。相反，在开始事务时设置`writeConcern`选项。

返回值

一个MongoDB\UpdateResult对象，该对象封装了一个MongoDB\Driver\WriteResult对象。

错误/异常

如果选项被使用且所选服务器不支持（例如 collation、readConcern、writeConcern），将抛出 MongoDB\Exception\UnsupportedException。

对于与参数或选项解析相关的错误，将抛出 MongoDB\Exception\InvalidArgumentException。

对于与写操作相关的错误，将抛出 MongoDB\Driver\Exception\BulkWriteException。用户应检查 getWriteResult() 返回的值以确定错误的性质。

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

行为

When evaluating query criteria, MongoDB compares types and values according to its own comparison rules for BSON types, which differs from PHP's comparison and type juggling rules. When matching a special BSON type the query criteria should use the respective BSON class in the extension (e.g. use MongoDB\BSON\ObjectId to match an ObjectId).

如果抛出了 MongoDB\Driver\Exception\BulkWriteException 异常，用户应调用 getWriteResult() 并检查返回的 MongoDB\Driver\WriteResult 对象以确定错误的性质。

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

示例

以下示例用测试数据库中restaurants集合的"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)

另请参阅

rename()

updateMany()