insert (database command)（数据库命名）

Definition定义

insert

The insert command inserts one or more documents and returns a document containing the status of all inserts. The insert methods provided by the MongoDB drivers use this command internally.insert命令插入一个或多个文档，并返回一个包含所有插入状态的文档。MongoDB驱动程序提供的插入方法在内部使用此命令。

Tip

In mongosh, this command can also be run through the db.collection.insertOne() and db.collection.insertMany() helper methods.在mongosh中，此命令也可以通过db.collection.insertOne()和db.collection.insertMany()辅助方法运行。

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.助手方法对mongosh用户来说很方便，但它们可能不会返回与数据库命令相同级别的信息。如果不需要便利性或需要额外的返回字段，请使用database命令。

Returns:返回：	A document that contains the status of the operation. See Output for details.包含操作状态的文档。详见输出。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用：

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

The command has the following syntax:该命令具有以下语法：

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

Command Fields命令字段

The command takes the following fields:该命令包含以下字段：

Behavior行为

Examples示例

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

Output输出

The returned document contains a subset of the following fields:返回的文档包含以下字段的子集：

insert.ok

The status of the command.命令的状态。

insert.n

The number of documents inserted.插入的文档数量。

insert.writeErrors

An array of documents that contains information regarding any error encountered during the insert operation. The writeErrors array contains an error document for each insert that errors.一组文档，其中包含有关插入操作期间遇到的任何错误的信息。writeErrors数组包含每个插入错误的错误文档。

Each error document contains the following fields:每个错误文档包含以下字段：

insert.writeErrors.index

An integer that identifies the document in the documents array, which uses a zero-based index.一个整数，用于标识documents数组中的文档，该数组使用从零开始的索引。

insert.writeErrors.code

An integer value identifying the error.标识错误的整数值。

insert.writeErrors.errmsg

A description of the error.错误的描述。

insert.writeConcernError

Document describing errors that relate to the write concern.描述与写入关注相关的错误的文档。

Changed in version 7.0.6.在版本7.0.6中的更改。 (also available in 6.0.14 and 5.0.30也可在6.0.14和5.0.30中使用): When insert executes on mongos, write concern errors are always reported, even when one or more write errors occur. 当在mongos上执行insert时，即使出现一个或多个写入错误，也总是会报告写入关注错误。In previous releases, the occurrence of write errors could cause the insert to not report write concern errors.在以前的版本中，写入错误的发生可能会导致insert不报告写入关注错误。

The writeConcernError documents contain the following fields:writeConcernError文档包含以下字段：

insert.writeConcernError.code

An integer value identifying the cause of the write concern error.一个整数值，用于标识写入关注错误的原因。

insert.writeConcernError.errmsg

A description of the cause of the write concern error.写入关注错误原因的描述。

insert.writeConcernError.errInfo.writeConcern

The write concern object used for the corresponding operation. For information on write concern object fields, see Write Concern Specification.用于相应操作的写关注对象。有关写入关注对象字段的信息，请参阅写入关注规范。

The write concern object may also contain the following field, indicating the source of the write concern:写入关注对象还可以包含以下字段，指示写入关注的来源：

insert.writeConcernError.errInfo.writeConcern.provenance

A string value indicating where the write concern originated (known as write concern provenance). The following table shows the possible values for this field and their significance:一个字符串值，指示写关注的来源（称为写关注provenance（来源））。下表显示了此字段的可能值及其意义：

Provenance来源	Description描述
clientSupplied	The write concern was specified in the application.应用程序中指定了写入关注。
customDefault	The write concern originated from a custom defined default value. 写入关注源于自定义的默认值。See setDefaultRWConcern.请参阅setDefaultRWConcern。
getLastErrorDefaults	The write concern originated from the replica set's settings.getLastErrorDefaults field.写入关注源于副本集的settings.getLastErrorDefaults字段。
implicitDefault	The write concern originated from the server in absence of all other write concern specifications.在没有所有其他写入关注规范的情况下，写入关注源自服务器。

The following is an example document returned for a successful insert of a single document:以下是成功insert单个文档时返回的示例文档：

{ ok: 1, n: 1 }

The following is an example document returned for an insert of two documents that successfully inserted one document but encountered an error with the other document:以下是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 }"
      }
   ]
}