insert

在此页面上

定义

兼容性
语法
命令字段
行为
示例
输出

定义

insert

insert命令会插入一个或多个文档，并返回一个包含所有插入状态的文档。MongoDB 驱动程序提供的插入方法会在内部使用此命令。

提示

在 mongosh 中，还可以通过 db.collection.insertOne() 和 db.collection.insertMany()辅助方法运行此命令。

辅助方法对 mongosh 用户来说很方便，但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段，请使用数据库命令。

返回：	包含操作状态的文档。有关详细信息，请参阅输出。

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

注意

所有MongoDB Atlas集群都支持此命令。有关Atlas支持所有命令的信息，请参阅不支持的命令。

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

该命令具有以下语法：

db.runCommand(
   {
      insert: <collection>,
      documents: [ <document>, <document>, <document>, ... ],
      ordered: <boolean>,
      maxTimeMS: <integer>,
      writeConcern: { <write concern> },
      bypassDocumentValidation: <boolean>,
      comment: <any>
   }
)

命令字段

该命令接受以下字段：

字段	类型	说明
`insert`	字符串	目标集合的名称。
`documents`	阵列	要插入到已命名集合中的一个或多个文档的数组。
`ordered`	布尔	可选。如果为`true`，则当插入文档失败时，返回而不插入`inserts`数组中列出的任何剩余文档。如果是`false`，那么当插入一个文档失败时，继续插入剩余的文档。默认为`true` 。
`maxTimeMS`	non-negative integer	可选。指定时间限制（以毫秒为单位）。如果您未指定 `maxTimeMS` 值，操作将不会超时。如果值为 `0` ，则显式指定默认无限制行为。 MongoDB 使用与 `db.killOp()` 相同的机制终止超过分配的时间限制的操作。MongoDB 仅在指定的中断点之一中终止操作。
`writeConcern`	文档	可选。用于表达 `insert` 命令写关注的文档。省略以使用默认的写关注。如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。
`bypassDocumentValidation`	布尔	可选。启用 `insert` 可在操作过程中绕过文档验证。这样就可以插入不符合验证要求的文档。
`comment`	any	可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置： mongod 日志消息，位于 `attr.command.cursor.comment` 字段中。 `command.comment` 字段中的数据库分析器输出。 `currentOp` 输出，在 `command.comment` 字段。注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。

行为

大小限制

所有 documents 数组元素的总大小必须小于或等于最大 BSON 文档大小。

documents 数组中的文档总数必须小于或等于最大批量大小。

文档验证

insert 命令可为 bypassDocumentValidation 选项添加支持，以便在附带验证规则的集合中插入或更新文档时绕过文档验证。

事务

insert 可以在分布式事务中使用。

重要

在大多数情况下，与单文档写入操作相比，分布式事务会产生更高的性能成本，并且分布式事务的可用性不应取代有效的模式设计。在许多情况下，非规范化数据模型（嵌入式文档和数组）仍然是数据和使用案例的最佳选择。换言之，对于许多场景，适当的数据建模将最大限度地减少对分布式事务的需求。

有关其他事务使用注意事项（如运行时间限制和 oplog 大小限制），另请参阅生产注意事项。

在事务中创建集合

如果事务不是跨分片写事务，则可以在分布式事务中创建集合和索引。

如果在事务中对不存在的集合指定插入操作，则 MongoDB 会隐式创建该集合。

提示

另请参阅：

在事务中创建集合和索引

写关注和事务

如果是在事务中运行，则请勿显式设置此操作的写关注。要将写关注与事务一起使用，请参阅事务和写关注。

插入不准确

即使在插入过程中遇到服务器错误，某些文档也可能已插入。

插入成功后，系统会返回 insert.n，即已插入集合的文档数。如果插入操作因副本集状态更改而中断，系统可能会继续插入文档。因此，insert.n 报告的文档可能少于实际插入的文档。

示例

插入单一文档

将文档插入到 users 集合中：

db.runCommand(
   {
      insert: "users",
      documents: [ { _id: 1, user: "abc123", status: "A" } ]
   }
)

返回的文档会显示该命令已成功插入文档。请参阅输出以了解详情。

{ "ok" : 1, "n" : 1 }

Bulk Insert

将三个文档插入users集合中：

db.runCommand(
   {
      insert: "users",
      documents: [
         { _id: 2, user: "ijk123", status: "A" },
         { _id: 3, user: "xyz123", status: "P" },
         { _id: 4, user: "mop123", status: "P" }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

返回的文档会显示该命令已成功插入这三个文档。请参阅输出以了解详情。

{ "ok" : 1, "n" : 3 }

结合使用插入与 `bypassDocumentValidation`

如果将 schema validation validationActions 设为 error，则插入到集合的文档会因违反模式验证规则而返回错误。要插入可能违反这些规则的文档，请设置 bypassDocumentValidation: true。

使用 status 字段上的验证规则创建 user 集合。

以下验证规则将验证状态必须为“Unknown”或“Incomplete”：

db.createCollection("users", {
   validator:
      {
         status: {
            $in: [ "Unknown", "Incomplete" ]
         }
      }
})

试图插入违反验证规则的文档：

db.runCommand({
      insert: "users",
      documents: [ {user: "123", status: "Active" } ]
})

插入返回写入错误消息：

{
   n: 0,
   writeErrors: [
      {
         index: 0,
         code: 121,
         errInfo: {
            failingDocumentId: ObjectId('6197a7f2d84e85d1cc90d270'),
            details: {
               operatorName: '$in',
               specifiedAs: { status: { '$in': [Array] } },
               reason: 'no matching value found in array',
               consideredValue: 'Active'
            }
         },
         errmsg: 'Document failed validation'
      }
   ],
   ok: 1
}

设置bypassDocumentValidation : true并重新运行插入操作：

db.runCommand({
   insert: "users",
   documents: [ {user: "123", status: "Active" } ],
   bypassDocumentValidation: true
})

操作成功。

要检查是否有违反模式验证规则的文档，请使用 validate 命令。

输出

返回的文档包含以下字段的子集：

insert.ok: 命令的状态。

insert.n: 插入的文档数量。

insert.writeErrors

包含插入操作过程中遇到的任何错误信息的文档数组。writeErrors 数组包含每个出错插入操作的错误文档。

每个错误文档都包含以下字段：

insert.writeErrors.index: 一个整数，可用于标识documents数组中的文档，而该数组会使用从零开始的索引。

insert.writeErrors.code: 标识错误的整数值。

insert.writeErrors.errmsg: 错误描述。

insert.writeConcernError

描述与写关注（write concern）相关的错误的文档。

在版本7.1中进行了更改：在insert }mongos 上执行时，即使出现一个或多个写入错误，也始终会报告写关注错误。

在以前的版本中，发生写入错误可能会导致insert不报告写关注（write concern）错误。

writeConcernError文档包含以下字段：

insert.writeConcernError.code: 一个整数值，用于标识写关注错误原因。

insert.writeConcernError.errmsg: 写关注错误原因的描述。

insert.writeConcernError.errInfo.writeConcern

用于相应操作的写关注对象。有关写关注对象字段的信息，请参阅写关注规范。

写关注对象还可能包含以下字段，指示写关注的来源：

insert.writeConcernError.errInfo.writeConcern.provenance

一个表示写关注来源（称为写关注provenance）的字符串值。下表显示该字段的可能值及其有效位数：

来源	说明
`clientSupplied`	应用程序中指定了写关注。
`customDefault`	写入关注源自自定义的默认值。请参阅 `setDefaultRWConcern`。
`getLastErrorDefaults`	写关注源自副本集的 `settings.getLastErrorDefaults` 字段。
`implicitDefault`	在没有所有其他写入关注规范的情况下，写入关注源自服务器。

以下是成功 insert 单个文档后返回的文档示例：

{ ok: 1, n: 1 }

在以下示例中，系统会为两个文档的 insert 返回一个示例文档；其中，这两个文档已成功插入一个文档，但在处理另一文档时出现错误：

{
   "ok" : 1,
   "n" : 1,
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 11000,
         "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.users.$_id_  dup key: { : 1.0 }"
      }
   ]
}

后退

getmore

来年

resetError

定义

提示

兼容性

注意

语法