插入

本页面

定义

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

定义

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>
   }
)

命令字段

该命令包含以下字段

字段	类型	描述
`插入`	字符串	目标集合的名称。
`文档`	数组	一个或多个文档的数组，要插入到指定名称的集合中。
`有序`	布尔值	可选。如果 `true`，则在插入文档失败时，将不会插入 `inserts` 数组中列出的任何剩余文档。如果 `false`，则在插入文档失败时，将继续插入剩余文档。默认为 `true`。
`maxTimeMS`	非负整数	可选。指定以毫秒为单位的时间限制。如果您未指定 `maxTimeMS` 的值，则操作不会超时。显式指定 `0` 的值将明确指定默认的无限制行为。 MongoDB 使用与 `db.killOp()` 相同的机制来终止超出其分配时间限制的操作。MongoDB 只在指定的中断点中终止一个操作。
`writeConcern`	文档	可选。一个文档，用于表达写入关注的 `insert` 命令。省略以使用默认写入关注。如果在一个事务中运行操作，不要显式设置操作的写入关注。有关使用事务中的写入关注的信息，请参阅事务和写入关注。
`bypassDocumentValidation`	布尔值	可选。允许在操作期间绕过文档验证。这可以让您插入不满足验证要求的文档。
`comment`	任何	可选。用户提供的注释，用于附加到此命令。设置后，此注释将显示在以下位置的此命令的记录旁边 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 }

批量插入

将三个文档插入到 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 设置为 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

描述与写关注相关的错误的文档。

变更版本7.1: 当在insert在mongos上执行时，即使发生一个或多个写错误，也会始终报告写关注错误。

在之前版本中，写错误的发生可能导致insert不报告写关注错误。

writeConcernError文档包含以下字段

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

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

insert.writeConcernError.errInfo.writeConcern

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

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

insert.writeConcernError.errInfo.writeConcern.provenance

一个字符串值，指示写入关注来源的位置（称为写入关注 provenance）。下表显示了该字段的可能值及其意义

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

以下是一个成功插入单个文档后返回的示例文档

{ ok: 1, n: 1 }

以下是一个插入两个文档后返回的示例文档，其中一个文档成功插入，但另一个文档遇到了错误

{
   "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

定义

提示

兼容性

注意

语法