Insert Documents

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, documents stored in a collection require a unique _id field that acts as a primary key. If the _id field is unspecified in the documents, MongoDB uses ObjectIds as the default value for the _id field; i.e. if a document does not contain a top-level _id field during an insert, the MongoDB driver adds the _id field that holds an ObjectId.

In addition, if the mongod receives a document to insert that does not contain an _id field (e.g. through an update operation with an upsert option) mongod will add the _id field that holds an ObjectId.

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"
   }
)

The method returns a document with the status of the operation:

{
   "acknowledged" : true,
   "insertedId" : ObjectId("5742045ecacf0ba0c3fa82b0")
}

To verify the inserted document, query the collection by specifying a query filter on the _id field:

db.users.find( { _id: ObjectId("5742045ecacf0ba0c3fa82b0") } )

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.

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

The method returns a document with the status of the operation:

{
   "acknowledged" : true,
   "insertedIds" : [
      ObjectId("57420d48cacf0ba0c3fa82b1"),
      ObjectId("57420d48cacf0ba0c3fa82b2"),
      ObjectId("57420d48cacf0ba0c3fa82b3")
   ]
}

To verify the inserted document, query the collection by specifying a query filter on the _id field:

db.users.find(
   { _id:
      { $in:
         [
            ObjectId("57420d48cacf0ba0c3fa82b1"),
            ObjectId("57420d48cacf0ba0c3fa82b2"),
            ObjectId("57420d48cacf0ba0c3fa82b3")
         ]
      }
   }
)

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"
   }
)

The operation returns a WriteResult object with the status of the operation. A successful insert of the document 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:

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.