MongoDB\Collection::insertMany()

本页内容

定义

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

定义

MongoDB\Collection::insertMany()

插入多个文档。

function insertMany(
    array $documents,
    array $options = []
): MongoDB\InsertManyResult

参数

$documents : 数组

要插入集合中的文档。

$options : 数组

指定所需选项的数组。

名称	类型	描述
bypassDocumentValidation	布尔值	如果 `true`，允许写操作绕过文档级别的验证。默认为 `false`。
codec	MongoDB\Codec\DocumentCodec	用于编码或解码文档的codec。此选项与 `typeMap` 选项互斥。默认为集合的 codec。默认 `codec` 选项的继承优先于 `typeMap` 选项。 New自版本1.17.
注释	mixed	允许用户指定任意注释，以帮助通过数据库分析器、当前操作输出和日志。此选项自 MongoDB 4.4 起可用，如果为较旧的服务器版本指定，则在执行时将引发异常。 New自版本1.13.
ordered	布尔值	如果 `true`：单个写操作失败时，操作将停止，不执行剩余的写操作，并抛出异常。如果 `false`：单个写操作失败时，如果还有剩余的写操作，操作将继续执行，并抛出异常。默认为 `true`。
session	MongoDB\Driver\Session	与操作关联的客户端会话。 New自版本1.3.
writeConcern	MongoDB\Driver\WriteConcern	使用操作的写关注。默认为集合的写关注。在事务中无法为单个操作指定写关注。相反，在启动事务时设置 `writeConcern` 选项。

返回值

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

错误/异常

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

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

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

行为

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

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

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

示例

以下操作将两个文档插入到 users 集合中的 test 数据库。

<?php
$collection = (new MongoDB\Client)->test->users;
$insertManyResult = $collection->insertMany([
    [
        'username' => 'admin',
        'email' => 'admin@example.com',
        'name' => 'Admin User',
    ],
    [
        'username' => 'test',
        'email' => 'test@example.com',
        'name' => 'Test User',
    ],
]);
printf("Inserted %d document(s)\n", $insertManyResult->getInsertedCount());
var_dump($insertManyResult->getInsertedIds());

输出将类似于

Inserted 2 document(s)
array(2) {
  [0]=>
  object(MongoDB\BSON\ObjectId)#11 (1) {
    ["oid"]=>
    string(24) "579a25921f417dd1e5518141"
  }
  [1]=>
  object(MongoDB\BSON\ObjectId)#12 (1) {
    ["oid"]=>
    string(24) "579a25921f417dd1e5518142"
  }
}

另请参阅

getWriteConcern()

下一步

insertOne()