- Reference >
- JavaScript Methods >
- db.collection.insert()
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 themongod
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 theinsert()
method as in the following:This operation inserts a new document into the
products
collection with theitem
field set tocard
, theqty
field set to15
, and the_id
field set to a uniqueObjectId
:Note
Most MongoDB driver clients will include the
_id
field and generate anObjectId
before sending the insert operation to MongoDB; however, if the client sends a document without an_id
field, themongod
will add the_id
field and generate theObjectId
.To insert a single document, with a custom
_id
field, include the_id
field set to a unique identifier and pass the document to theinsert()
method as follows:This operation inserts a new document in the
products
collection with the_id
field set to10
, theitem
field set tobox
, theqty
field set to20
:Note
Most MongoDB driver clients will include the
_id
field and generate anObjectId
before sending the insert operation to MongoDB; however, if the client sends a document without an_id
field, themongod
will add the_id
field and generate theObjectId
.To insert multiple documents, pass an array of documents to the
insert()
method as in the following:The operation will insert three documents into the
products
collection:- A document with the fields
_id
set to11
,item
set topencil
,qty
set to50
, and thetype
set tono.2
. - A document with the fields
_id
set to a uniqueobjectid
,item
set topen
, andqty
set to20
. - A document with the fields
_id
set to a uniqueobjectid
,item
set toeraser
, andqty
set to25
.
- A document with the fields
- If the collection does not exist, then the