Docs Home → MongoDB Manual

insert

On this page本页内容

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. 助手方法对mongosh用户来说很方便，但它们可能不会返回与数据库命令相同级别的信息。In cases where the convenience is not needed or the additional return fields are required, use the database command.如果不需要方便，或者需要额外的返回字段，请使用数据库命令。

Returns:返回值：A document that contains the status of the operation. See Output for details.包含操作状态的文档。有关详细信息，请参阅输出。

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:该命令包含以下字段：

Field字段Type类型Description描述
insertstringThe name of the target collection.目标集合的名称。
documentsarrayAn array of one or more documents to insert into the named collection.要插入到命名集合中的一个或多个文档的数组。
orderedbooleanOptional.可选的。If true, then when an insert of a document fails, return without inserting any remaining documents listed in the inserts array. 如果为true，则当插入文档失败时，返回时不插入inserts数组中列出的任何剩余文档。If false, then when an insert of a document fails, continue to insert the remaining documents. 如果为false，则当插入文档失败时，继续插入其余文档。Defaults to true.默认为true。
maxTimeMSnon-negative integerOptional.可选的。
Specifies a time limit in milliseconds. 指定以毫秒为单位的时间限制。If you do not specify a value for maxTimeMS, operations will not time out. 如果不指定maxTimeMS的值，操作将不会超时。A value of 0 explicitly specifies the default unbounded behavior.值0显式指定默认的无边界行为。
MongoDB terminates operations that exceed their allotted time limit using the same mechanism as db.killOp(). MongoDB only terminates an operation at one of its designated interrupt points. MongoDB使用与db.killOp()相同的机制终止超过指定时间限制的操作。MongoDB只在其指定的中断点之一终止操作。
writeConcerndocumentOptional.可选的。A document that expresses the write concern of the insert command. Omit to use the default write concern.表示insert命令的写入关注的文档。忽略使用默认的写入关注。
Do not explicitly set the write concern for the operation if run in a transaction. 如果在事务中运行，请不要显式设置操作的写入关注。To use write concern with transactions, see Transactions and Write Concern. 要在事务中使用写入关注，请参阅事务和写入关注。
bypassDocumentValidationbooleanOptional.可选的。Enables insert to bypass document validation during the operation. 启用insert以在操作过程中绕过文档验证。This lets you insert documents that do not meet the validation requirements.这样可以插入不符合验证要求的文档。
commentanyOptional.可选的。
A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: 要附加到此命令的用户提供的注释。设置后，此注释将与此命令的记录一起显示在以下位置： A comment can be any valid BSON type (string, integer, object, array, etc). 注释可以是任何有效的BSON类型（字符串、整数、对象、数组等）。
New in version 4.4. 4.4版新增。

Behavior行为

Size Limit大小限制

The total size of all the documents array elements must be less than or equal to the maximum BSON document size.所有documents数组元素的总大小必须小于或等于BSON文档的最大大小。

The total number of documents in the documents array must be less than or equal to the maximum bulk size.documents数组中的文档总数必须小于或等于最大批量大小。

Document Validation文件验证

The insert command adds support for the bypassDocumentValidation option, which lets you bypass document validation when inserting or updating documents in a collection with validation rules.insert命令添加了对bypassDocumentValidation选项的支持，该选项允许您在使用验证规则插入或更新集合中的文档时绕过文档验证。

Transactions事务

insert can be used inside multi-document transactions.可以在多文档事务中使用。

Important

In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transactions should not be a replacement for effective schema design. 在大多数情况下，与单文档写入相比，多文档事务会产生更高的性能成本，并且多文档事务的可用性不应取代有效的模式设计。For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. 对于许多场景，非规范化数据模型（嵌入文档和数组）将继续是您的数据和用例的最佳选择。That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions.也就是说，对于许多场景，对数据进行适当建模将最大限度地减少对多文档事务的需求。

For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.有关其他事务使用注意事项（如运行时限制和操作日志大小限制），请参阅生产注意事项。

Collection Creation in Transactions事务记录中的集合创建

Starting in MongoDB 4.4, you can create collections and indexes inside a multi-document transaction if the transaction is not a cross-shard write transaction.从MongoDB 4.4开始，如果多文档事务不是跨分片写入事务，则可以在该事务内创建集合和索引。

Specifically, in MongoDB 4.4 and greater, if you specify an insert on a non-existing collection in a transaction, the collection is implicitly created.具体来说，在MongoDB 4.4及更高版本中，如果在事务中的不存在集合上指定插入，则会隐式创建该集合。

In MongoDB 4.4 and earlier, the operation must be run on an existing collection.在MongoDB 4.4及更早版本中，操作必须在现有集合上运行。

Tip

See also: 另请参阅：

Create Collections and Indexes In a Transaction在事务中创建集合和索引

Write Concerns and Transactions撰写关注事项和事务

Do not explicitly set the write concern for the operation if run in a transaction. 如果在事务中运行，请不要显式设置操作的写入关注。To use write concern with transactions, see Transactions and Write Concern.要在事务中使用写入关注，请参阅事务和写入关注。

Insert Inaccuracies插入不准确

Even if you encounter a server error during an insert, some documents may have been inserted.即使在插入过程中遇到服务器错误，也可能已插入某些文档。

After a successful insert, the system returns insert.n, the number of documents inserted into the collection. 成功插入后，系统返回insert.n，即插入集合中的文档数。If the insert operation is interrupted by a replica set state change, the system may continue inserting documents. 如果插入操作因副本集状态更改而中断，系统可以继续插入文档。As a result, insert.n may report fewer documents than actually inserted.因此，insert.n报告的文档可能比实际插入的文档少。

Examples实例

Insert a Single Document插入单个文档

Insert a document into the users collection:将文档插入users集合：

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

The returned document shows that the command successfully inserted a document. 返回的文档显示该命令已成功插入文档。See Output for details.有关详细信息，请参阅输出。

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

Bulk Insert批量插入

Insert three documents into the users collection:在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 }
   }
)

The returned document shows that the command successfully inserted the three documents. See Output for details.返回的文档显示该命令成功插入了这三个文档。有关详细信息，请参阅输出。

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

Using Insert with bypassDocumentValidation将Insert与bypassDocumentValidation一起使用

If schema validation validationActions are set to error, inserts to a collection return errors for documents that violate the schema validation rules. 如果架构验证validationActions设置为error，则插入到集合中会返回违反架构验证规则的文档的错误。To insert documents which would violate these rules set bypassDocumentValidation: true.插入将违反bypassDocumentValidation: true设置的这些规则的文档。

Create the user collection with a validation rule on the status fields.使用status字段的验证规则创建user集合。

The validation rule validates that the status must be "Unknown" or "Incomplete":验证规则验证状态必须为“未知”或“未完成”：

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

Attempt to insert a document which violates the validation rule:尝试插入违反验证规则的文档：

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

The insert returns a write error message:插入返回一条写入错误消息：

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

Set bypassDocumentValidation : true and rerun the insert:设置bypassDocumentValidation : true并重新运行插入：

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

The operation succeeds.操作成功。

To check for documents that violate schema validation rules, use the validate command.若要检查是否存在违反架构验证规则的文档，请使用validate命令。

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 that describe error related to write concern and contains the field:描述与写入关注相关的错误并包含以下字段的文档：

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

New in version 4.4. 4.4版新增。

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描述
clientSuppliedThe write concern was specified in the application.写入关注已在应用程序中指定。
customDefaultThe write concern originated from a custom defined default value. 写入关注源自自定义定义的默认值。See setDefaultRWConcern.
getLastErrorDefaultsThe write concern originated from the replica set's settings.getLastErrorDefaults field.写入关注源自复制副本集的settings.getLastErrorDefaults字段。
implicitDefaultThe 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 }"
      }
   ]
}