insert

定义

insert

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

提示

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

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

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

兼容性

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

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

• MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本

• MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

该命令具有以下语法：

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

insert 命令采用以下字段：

行为

示例

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

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

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 }

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
}

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

输出

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

insert.ok

命令的状态。

insert.n

插入的文档数量。

insert.writeErrors

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

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

insert.writeErrors.index

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

insert.writeErrors.code

标识错误的整数值。

insert.writeErrors.errmsg

错误描述。

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	在没有所有其他写入关注规范的情况下，写入关注源自服务器。

以下是成功 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 }"
      }
   ]
}