- MongoDB CRUD Operations >
- Insert Documents
Insert Documents¶
On this page
Insert Methods¶
MongoDB provides the following methods for inserting documents into a collection:
This page provides examples of insert operations in the
mongo
shell.
Insert Behavior¶
Collection Creation¶
If the collection does not currently exist, insert operations will create the collection.
_id
Field¶
In MongoDB, each document stored in a collection requires a unique
_id field that acts as a primary key. If an inserted
document omits the _id
field, the MongoDB driver automatically
generates an ObjectId for the _id
field.
This also applies to documents inserted through update operations with upsert: true.
Atomicity¶
All write operations in MongoDB are atomic on the level of a single document. For more information on MongoDB and atomicity, see Atomicity and Transactions
db.collection.insertOne()
¶
New in version 3.2.
db.collection.insertOne()
inserts a single document into a collection.
The following example inserts a new document into the users
collection. The new document has three fields name
, age
, and
status
. Since the document does not specify an _id
field,
MongoDB adds the _id
field with an ObjectId value to the new
document. See Insert Behavior.
You can run this method in the web shell below:
insertOne()
will return a document providing the
inserted document’s _id
field. See the
reference for an example.
To retrieve the document that you just inserted, query the collection:
For more information and examples, see
db.collection.insertOne()
.
db.collection.insertMany()
¶
New in version 3.2.
db.collection.insertMany()
inserts multiple documents into a collection.
The following example inserts three new documents into the users
collection. Each document has three fields name
, age
, and
status
. Since the documents do not specify an _id
field,
MongoDB adds the _id
field with an ObjectId value to each document.
See Insert Behavior.
You can run this method in the web shell below:
insertMany()
will return a document providing
each inserted document’s _id
field. See the
reference for an example.
To retrieve the inserted documents, query the collection:
For more information and examples, see
db.collection.insertMany()
.
db.collection.insert()
¶
db.collection.insert()
inserts a single document or multiple
documents into a collection. To insert a single document, pass a
document to the method; to insert multiple documents, pass an array of
documents to the method.
The following example inserts a new document into the users
collection. The new document has three fields name
, age
, and
status
. Since the document does not specify an _id
field,
MongoDB adds the _id
field with an ObjectId value to the document.
See Insert Behavior.
You can run this method in the web shell below:
db.collection.insert
returns a WriteResult
object
providing status information.
For example, a successful insert returns the following
WriteResult
object:
The nInserted
field specifies the number of
documents inserted. If the operation encounters an error, the
WriteResult
object will contain the error information.
The following example inserts multiple documents into the users
collection. Since the documents do not specify an _id
field,
MongoDB adds the _id
field with an ObjectId value to each document.
See Insert Behavior.
The method returns a BulkWriteResult
object with the status
of the operation. A successful insert of the documents returns the
following BulkWriteResult
object:
For more information and examples, see db.collection.insert()
.
Additional Methods¶
The following methods can also add new documents to a collection:
db.collection.update()
when used with theupsert: true
option.db.collection.updateOne()
when used with theupsert: true
option.db.collection.updateMany()
when used with theupsert: true
option.db.collection.findAndModify()
when used with theupsert: true
option.db.collection.findOneAndUpdate()
when used with theupsert: true
option.db.collection.findOneAndReplace()
when used with theupsert: true
option.db.collection.save()
.db.collection.bulkWrite()
.
See the individual reference pages for the methods for more information and examples.
Write Acknowledgement¶
With write concerns, you can specify the level of acknowledgement requested from MongoDB for write operations. For details, see Write Concern.