MongoDB\Collection::bulkWrite()

在此页面上

定义
参数
Return Values
错误/异常
行为
另请参阅

定义

MongoDB\Collection::bulkWrite()

执行多个写操作。

function bulkWrite(
    array $operations,
    array $options = []
): MongoDB\BulkWriteResult

参数

$operations : array

包含要执行的写入操作的数组。 MongoDB\Collection::bulkWrite()支持以下数组结构中的MongoDB\Collection::deleteMany() 、 MongoDB\Collection::deleteOne() 、 MongoDB\Collection::insertOne() 、 MongoDB\Collection::replaceOne() 、 MongoDB\Collection::updateMany()和MongoDB\Collection::updateOne()操作：

[
    [ 'deleteMany' => [ $filter ] ],
    [ 'deleteOne'  => [ $filter ] ],
    [ 'insertOne'  => [ $document ] ],
    [ 'replaceOne' => [ $filter, $replacement, $options ] ],
    [ 'updateMany' => [ $filter, $update, $options ] ],
    [ 'updateOne'  => [ $filter, $update, $options ] ],
]

参数对应于各自的操作方法。但是，writeConcern 选项被指定为 MongoDB\Collection::bulkWrite() 的顶级选项，而不是每个单独的操作。

$options : array

指定所需选项的数组。

名称	类型	说明
builderEncoder	MongoDB\Codec\Encoder	用于查询和聚合构建者的编码器。如果未设立，此选项默认为 `MongoDB\Builder\BuilderEncoder` 类的新实例。 1.21版本新增。
bypassDocumentValidation	布尔	如果为 `true`，则允许写入操作规避文档级验证。默认为 `false`。
编解码器	MongoDB\Codec\DocumentCodec	用于对文档进行编码或解码的编解码器。此选项与 `typeMap` 选项互斥。默认为集合的编解码器。默认 `codec` 选项的继承优先于 `typeMap` 选项的继承。批量写入使用编解码器进行`insertOne`和`replaceOne`操作。 1.17 版本中的新增功能。
comment	混合	使用户可以指定任意注释来帮助通过数据库分析器、currentOp 输出和日志来跟踪操作。自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。 1.13 版本中的新增功能。
let	数组\|对象	参数名称和值的映射。值必须是常量或不引用文档字段的封闭表达式。然后可以在聚合表达式上下文中将参数作为变量进行访问（例如 `$var`）。 5.0 之前的服务器版本不支持此功能，如果使用，将导致执行时出现异常。 1.13 版本中的新增功能。
ordered	布尔	如果`true` ：当单次写入失败时，操作将停止，不执行剩余写入，并抛出异常。如果`false` ：当单次写入失败时，操作将继续执行剩余的写入（如有），并抛出异常。默认为 `true`。
会话	MongoDB\Driver\Session	与操作相关联的客户端会话。 1.3 版本中的新增功能。
writeConcern	MongoDB\Driver\WriteConcern	写关注用于操作。默认为集合的写关注。无法将单个操作的写关注指定为事务的一部分。相反，请在`writeConcern` 启动事务时设置选项。

Return Values

一个MongoDB\BulkWriteResult 对象，其中封装了 MongoDB\Driver\WriteResult 对象。

错误/异常

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

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

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

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

行为

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

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

在批量写入的情况下，结果可能指示多个成功的写入操作和/或错误。如果ordered选项为true ，则在遇到第一个错误和抛出异常之前，某些操作可能已成功。如果ordered选项为false ，则可能遇到多个错误。

另请参阅

后退

聚合(aggregate)()

来年

COUNT()