db.collection.insert()¶

db.collection.insert(document)¶

The insert() method inserts a document or documents into a collection.

Changed in version 2.2: The insert() method can accept an array of documents to perform a bulk insert of the documents into the collection.

Note

For bulk inserts on sharded clusters, the getLastError command alone is insufficient to verify success. Applications should must verify the success of bulk inserts in application logic.

Consider the following behaviors of the insert() method:

If the collection does not exist, then the insert() method will create the collection.
If the document does not specify an _id field, then MongoDB will add the _id field and assign a unique ObjectId for the document before inserting. Most drivers create an ObjectId and insert the _id field, but the mongod will create and populate the _id if the driver or application does not.
If the document specifies a new field, then the insert() method inserts the document with the new field. This requires no changes to the data model for the collection or the existing documents.

The insert() method takes one of the following parameters:

Parameters:	document – A document to insert into the collection. documents (array) – New in version 2.2. An array of documents to insert into the collection.

Consider the following examples of the insert() method:

To insert a single document and have MongoDB generate the unique _id, omit the _id field in the document and pass the document to the insert() method as in the following:
copy
```
db.products.insert( { item: "card", qty: 15 } )
```
This operation inserts a new document into the products collection with the item field set to card, the qty field set to 15, and the _id field set to a unique ObjectId:
copy
```
{ "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 }
```
Note

Most MongoDB driver clients will include the _id field and generate an ObjectId before sending the insert operation to MongoDB; however, if the client sends a document without an _id field, the mongod will add the _id field and generate the ObjectId.
To insert a single document, with a custom _id field, include the _id field set to a unique identifier and pass the document to the insert() method as follows:
copy
```
db.products.insert( { _id: 10, item: "box", qty: 20 } )
```
This operation inserts a new document in the products collection with the _id field set to 10, the item field set to box, the qty field set to 20:
copy
```
{ "_id" : 10, "item" : "box", "qty" : 20 }
```
Note

Most MongoDB driver clients will include the _id field and generate an ObjectId before sending the insert operation to MongoDB; however, if the client sends a document without an _id field, the mongod will add the _id field and generate the ObjectId.

To insert multiple documents, pass an array of documents to the insert() method as in the following:

copy

db.products.insert( [ { _id: 11, item: "pencil", qty: 50, type: "no.2" },
                      {          item: "pen", qty: 20 },
                      {          item: "eraser", qty: 25 } ] )

The operation will insert three documents into the products collection:

A document with the fields _id set to 11, item set to pencil, qty set to 50, and the type set to no.2.
A document with the fields _id set to a unique objectid, item set to pen, and qty set to 20.
A document with the fields _id set to a unique objectid, item set to eraser, and qty set to 25.

copy

{ "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" }
{ "_id" : ObjectId("50631bc0be4617f17bb159ca"), "item" : "pen", "qty" : 20 }
{ "_id" : ObjectId("50631bc0be4617f17bb159cb"), "item" : "eraser", "qty" : 25 }

← db.collection.group() db.collection.isCapped() →