- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.insert()
db.collection.insert()¶
On this page
Definition¶
-
db.collection.
insert
(document)¶ Inserts a document or an array of 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.Parameter Type Description document
document or array A document or array of documents to insert into the collection. The
insert()
method has the following behaviors:- 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.
- If the collection does not exist, then the
Examples¶
The following examples show how to use the
insert()
method to insert a document or an
array of documents into either the products
collection or the
bios
collection. If the collections do not exist, the
insert()
method creates the collections.
[1]
Insert a Document without Specifying an _id
Field¶
In the following examples, the document passed to the
insert()
method does not contain the _id
field. During the insert, mongod
will create the _id
field and assign it a unique ObjectId value.
The ObjectId
values are specific to the machine and time when the
operation is run. As such, your values may differ from those in the
example.
products
Collection¶
The following example inserts a document into the products
collection:
The inserted document includes an _id
field with the generated
ObjectId
value:
bios
Collection¶
The following example inserts a document into the The bios Example Collection:
To verify the inserted document, query the bios
collection:
The returned document includes an _id
field with the generated
ObjectId
value:
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
.
Insert a Document Specifying an _id
Field¶
In the following examples, the documents passed to the
insert()
method includes the _id
field.
The value of _id
must be unique within the collection to avoid
duplicate key error.
products
Collection¶
This example inserts into the products
collection a document that
includes an _id
field. The _id
value of 10
must be a unique
value for the _id
field in the products
collection. If the
value were not unique, the insert would fail:
The insert operation creates the following document in the products
collection:
bios
Collection¶
This example inserts into the bios
collection a document that
includes an _id
field. The _id
value of 1
must be a unique
value for the _id
field in the bios
collection. Otherwise, if
the value were not unique, the insert would fail:
To confirm the insert, query the bios
collection:
The insert operation created the following document in the bios
collection:
Insert Multiple Documents¶
The following examples perform a bulk insert of multiple documents by
passing an array of documents to the insert()
method.
products
Collection¶
This example inserts three documents into the products
collection.
The documents in the array do not need to have the same fields. For
instance, the first document in the array has an _id
field and a
type
field. Because the second and third documents do not contain
an _id
field, mongod
will create the _id
field for
the second and third documents during the insert:
The operation inserted the following three documents:
bios
Collection¶
This example inserts three documents in the bios
collection. The
documents in the array do not need to have the same fields. The
document with _id: 3
contains a field named title
that does not
appear in the other documents. MongoDB does not require the other
documents to contain this field:
[1] | You can also view a list of the existing
collections in the database using the show collections
operation in the mongo shell. |