MongoDB - MongoDB CRUD Operations, Insert Documents

MongoDB provides the following methods for inserting documents into a collection:

• db.collection.insertOne()
• db.collection.insertMany()
• db.collection.insert()

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.

db.users.insertOne(
   {
      name: "sue",
      age: 19,
      status: "P"
   }
)

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 _idfield with an ObjectId value to each document. See Insert Behavior.

db.users.insertMany(
   [
     { name: "bob", age: 42, status: "A", },
     { name: "ahn", age: 22, status: "A", },
     { name: "xi", age: 34, status: "D", }
   ]
)

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:

db.users.find()

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.

db.users.insert(
   {
      name: "sue",
      age: 19,
      status: "P"
   }
)

db.collection.insert returns a WriteResult object providing status information.

For example, a successful insert returns the following WriteResult object:

WriteResult({ "nInserted" : 1 })

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.

db.users.insert(
   [
     { name: "bob", age: 42, status: "A", },
     { name: "ahn", age: 22, status: "A", },
     { name: "xi", age: 34, status: "D", }
   ]
)

The method returns a BulkWriteResult object with the status of the operation. A successful insert of the documents returns the following BulkWriteResult object:

BulkWriteResult({
   "writeErrors" : [ ],
   "writeConcernErrors" : [ ],
   "nInserted" : 3,
   "nUpserted" : 0,
   "nMatched" : 0,
   "nModified" : 0,
   "nRemoved" : 0,
   "upserted" : [ ]
})

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 the upsert: true option.
• db.collection.updateOne() when used with the upsert: true option.
• db.collection.updateMany() when used with the upsert: true option.
• db.collection.findAndModify() when used with the upsert: true option.
• db.collection.findOneAndUpdate() when used with the upsert: true option.
• db.collection.findOneAndReplace() when used with the upsert: 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.