Docs 菜单

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 版本中的新增功能

排序规则

数组|对象

排序规则允许用户为string比较指定特定于语言的规则,例如字母大小写和重音符号规则。 指定排序规则时, locale字段为必填字段;所有其他排序规则字段都是可选的。 有关字段的说明,请参阅排序规则文档。

如果未指定排序规则但集合具有默认排序规则,则操作将使用为集合指定的排序规则。如果没有为集合或操作指定排序规则,MongoDB 将使用先前版本中用于字符串比较的简单二进制比较。

comment

混合

使用户可以指定任意注释来帮助通过数据库分析器currentOp 输出和日志来跟踪操作。

自 MongoDB 4.4 起此选项可用,如果为旧服务器版本指定,则会在执行时导致异常。

1.13 版本中的新增功能

提示

字符串|数组|对象

要使用的索引。将索引名称指定为字符串或将索引键模式指定为文档。如果指定,查询系统将只考虑使用提示索引的计划。

自 MongoDB 4.2 起此选项可用,如果为旧服务器版本指定,则会在执行时导致异常。

1.6 版本中的新增功能

let

数组|对象

参数名称和值的映射。值必须是常量或不引用文档字段的封闭表达式。然后可以在聚合表达式上下文中将参数作为变量进行访问(例如 $$var)。

5.0 之前的服务器版本不支持此功能,如果使用,将导致执行时出现异常。

1.13 版本中的新增功能

会话

与操作相关联的客户端会话。

1.3 版本中的新增功能

sort

数组|对象

匹配文档排序的排序规范。设置此选项可在服务器执行替换操作之前对匹配的文档应用顺序。

1.21版本新增

更新插入

布尔

如果设置为 true,则在没有文档符合查询条件时创建一个新文档。默认值为 false,在未找到匹配项时不插入新文档。

writeConcern

写关注用于操作。默认为集合的写关注。

无法将单个操作的写关注指定为事务的一部分。 相反,请在writeConcern 启动事务 时设置 选项。

一个MongoDB\UpdateResult 对象,其中封装了 MongoDB\Driver\WriteResult 对象。

MongoDB\Exception\UnsupportedException,如果所选服务器使用了选项但不支持选项(例如collationreadConcernwriteConcern)。

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

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