MongoDB\Collection::bulkWrite()

本页面内容

定义

参数
返回值
错误/异常
行为
另请参阅

定义

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

一个指定所需选项的数组。

名称	类型	描述
bypassDocumentValidation	布尔型	如果为 `true`，则允许写操作绕过文档级别的验证。默认为 `false`。
codec	MongoDB\Codec\DocumentCodec	用于编码或解码文档的 codec。此选项与 `typeMap` 选项互斥。默认为集合的 codec。默认 `codec` 选项的继承优先于 `typeMap` 选项。批量写入使用 `insertOne` 和 `replaceOne` 操作的 codec。新在版本1.17.
评论	混合型	允许用户指定任意注释，以帮助通过数据库分析器，当前操作输出和日志跟踪操作。此选项自 MongoDB 4.4 以来可用，如果为旧服务器版本指定，将在执行时引发异常。新在版本1.13.
let	array\|object	参数名称和值的映射。值必须是常量或封闭表达式，不能引用文档字段。然后可以在聚合表达式上下文中访问参数作为变量（例如 `$$var`）。此功能不支持 5.0 之前的服务器版本，如果使用则会在执行时引发异常。新在版本1.13.
ordered	布尔型	如果为 `true`：当单个写操作失败时，操作将停止，不执行剩余的写操作，并抛出异常。如果为 `false`：当单个写操作失败时，操作将继续执行剩余的写操作（如果有），并抛出异常。默认为 `true`。
session	MongoDB\Driver\Session	与操作关联的客户端会话。新在版本1.3.
writeConcern	MongoDB\Driver\WriteConcern	用于操作写关注。默认为集合的写关注。在事务中不能为单个操作指定写关注。相反，在启动事务时设置`writeConcern`选项。

返回值

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

错误/异常

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

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

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

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

行为

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

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

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

另请参阅

aggregate()

下一步

count()