- Reference >
- Database Commands >
- Query and Write Operation Commands >
- insert
insert¶
On this page
Definition¶
-
insert
¶ New in version 2.6.
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.The command has the following syntax:
The
insert
command takes the following fields:Field Type Description insert
string The name of the target collection. documents
array An array of one or more documents to insert into the named collection. ordered
boolean Optional. If true
, then when an insert of a document fails, return without inserting any remaining documents listed in theinserts
array. Iffalse
, then when an insert of a document fails, continue to insert the remaining documents. Defaults totrue
.writeConcern
document Optional. A document that expresses the write concern of the
insert
command. Omit to use the default write concern.Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Read Concern/Write Concern/Read Preference.
bypassDocumentValidation
boolean Optional. Enables
insert
to bypass document validation during the operation. This lets you insert documents that do not meet 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 less
than or equal to the maximum BSON document size
.
The total number of documents in the documents
array must be less
than or equal to the maximum bulk size
.
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.
Transactions¶
insert
supports multi-document transactions.
The collection must already exist. An insert operation that would result in the creation of a new collection are not allowed in a transaction.
Do not explicitly set the write concern for the operation if run in a transaction. To use write concern with transactions, see Read Concern/Write Concern/Read Preference.
Important
In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transaction 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.
Examples¶
Insert a Single Document¶
Insert a document into the users
collection:
The returned document shows that the command successfully inserted a document. See Output for details.
Bulk Insert¶
Insert three documents into the users
collection:
The returned document shows that the command successfully inserted the three documents. See Output for details.
Using Insert with bypassDocumentValidation
¶
If schema validation validationActions
are set to error
, inserts to a collection return errors for
documents that violate the schema validation rules. To insert documents
which would violate these rules set bypassDocumentValidation: true
.
Create the user
collection with a validation rule on the status
fields.
The validation rule validates that the status must be “Unknown” or “Incomplete”:
Attempt to insert a document which violates the validation rule:
The insert returns a write error message:
Set bypassDocumentValidation : true
and rerun the insert:
The operation succeeds.
To check for documents that violate schema validation rules, use the
validate
command.
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.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.
-
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.
-
The following is an example document returned for a successful
insert
of a single document:
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: