insert

Definition

  • insert

New in version 2.6.

The insert command inserts one or more documents andreturns a document containing the status of all inserts. The insertmethods provided by the MongoDB drivers use this command internally.

The command has the following syntax:

  1. {
  2.    insert: <collection>,
  3.    documents: [ <document>, <document>, <document>, ... ],
  4.    ordered: <boolean>,
  5.    writeConcern: { <write concern> },
  6.    bypassDocumentValidation: <boolean>
  7. }

The insert command takes the following fields:

FieldTypeDescriptioninsertstringThe 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 withoutinserting any remaining documents listed in the inserts array. Iffalse, then when an insert of a document fails, continue to insert theremaining documents. Defaults to true.writeConcerndocumentOptional. A document that expresses the write concernof the insert command. Omit to use the default writeconcern.

Do not explicitly set the write concern for the operation if run ina transaction. To use write concern with transactions, seeTransactions and Write Concern.bypassDocumentValidationbooleanOptional. Enables insert to bypass document validationduring the operation. This lets you insert documents that do notmeet the validation requirements.

New in version 3.2.

Returns:A document that contains the status of the operation.See Output for details.

Behavior

Size Limit

The total size of all the documents array elements must be lessthan or equal to the maximum BSON document size.

The total number of documents in the documents array must be lessthan or equal to the maximum bulk size.

Document Validation

The insert command adds support for thebypassDocumentValidation option, which lets you bypassdocument validation wheninserting or updating documents in a collection with validationrules.

Transactions

insert can be used inside multi-document transactions.

The collection must already exist. An insert operation thatwould result in the creation of a new collection are not allowed in atransaction.

Do not explicitly set the write concern for the operation if run ina transaction. To use write concern with transactions, seeTransactions and Write Concern.

Important

In most cases, multi-document transaction incurs a greaterperformance cost over single document writes, and theavailability of multi-document transactions should not be areplacement for effective schema design. For many scenarios, thedenormalized data model (embedded documents and arrays) will continue to be optimal for yourdata and use cases. That is, for many scenarios, modeling your dataappropriately will minimize the need for multi-documenttransactions.

For additional transactions usage considerations(such as runtime limit and oplog size limit), see alsoProduction Considerations.

Examples

Insert a Single Document

Insert a document into the users collection:

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

The returned document shows that the command successfully inserted adocument. See Output for details.

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

Bulk Insert

Insert three documents into the users collection:

  1. db.runCommand(
  2.    {
  3.       insert: "users",
  4.       documents: [
  5.          { _id: 2, user: "ijk123", status: "A" },
  6.          { _id: 3, user: "xyz123", status: "P" },
  7.          { _id: 4, user: "mop123", status: "P" }
  8.       ],
  9.       ordered: false,
  10.       writeConcern: { w: "majority", wtimeout: 5000 }
  11.    }
  12. )

The returned document shows that the command successfully inserted thethree documents. See Output for details.

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

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 errorencountered during the insert operation. ThewriteErrors array contains an error document foreach insert that errors.

Each error document contains the following fields:

  • insert.writeErrors.index

  • An integer that identifies the document in thedocuments array, which uses a zero-based index.

  • 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 containsthe 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.

The following is an example document returned for a successfulinsert of a single document:

  1. { ok: 1, n: 1 }

The following is an example document returned for aninsert of two documents that successfully inserted onedocument but encountered an error with the other document:

  1. {
  2.    "ok" : 1,
  3.    "n" : 1,
  4.    "writeErrors" : [
  5.       {
  6.          "index" : 1,
  7.          "code" : 11000,
  8.          "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.users.$_id_  dup key: { : 1.0 }"
  9.       }
  10.    ]
  11. }