MongoDB\Collection::insertMany()

在此页面上

定义

参数
Return Values
错误/异常
行为
例子
另请参阅

定义

MongoDB\Collection::insertMany()

插入多个文档。

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

参数

$documents : array

要插入到collection中的文档。

$options : array

指定所需选项的数组。

名称	类型	说明
bypassDocumentValidation	布尔	如果为 `true`，则允许写入操作规避文档级验证。默认为 `false`。
编解码器	MongoDB\Codec\DocumentCodec	用于对文档进行编码或解码的编解码器。此选项与`typeMap`选项互斥。默认为集合的编解码器。默认 `codec` 选项的继承优先于 `typeMap` 选项的继承。 1.17 版本中的新增功能。
comment	混合	允许用户指定任意注释，以帮助通过数据库分析器、 currentOp输出和日志跟踪操作。自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。 1.13 版本中的新增功能。
ordered	布尔	如果`true` ：当单次写入失败时，操作将停止，不执行剩余写入，并抛出异常。如果`false` ：当单次写入失败时，操作将继续执行剩余的写入（如有），并抛出异常。默认为 `true`。
会话	MongoDB\Driver\Session	与操作相关联的客户端会话。 1.3 版本中的新增功能。
writeConcern	MongoDB\Driver\WriteConcern	写关注用于操作。默认为集合的写关注。无法将单个操作的写关注指定为事务的一部分。相反，请在`writeConcern` 启动事务时设置选项。

Return Values

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

错误/异常

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

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

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

行为

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

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

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

例子

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

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