MongoDB\Collection::insertOne()

本页内容

定义

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

定义

MongoDB\Collection::insertOne()

插入一个文档。

function insertOne(
    array|object $document,
    array $options = []
): MongoDB\InsertOneResult

参数

$document : array|object

要插入集合的文档。

$options : 数组

指定所需选项的数组。

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

返回值

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

错误/异常

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

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

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

行为

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

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

示例

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

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

输出将类似于

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

另请参阅

insertMany()

listIndexes()