In MongoDB the db.collection.insert() method inserts a document or documents into a collection.

The collection part is the name of the collection to insert the document/s into.

Example

Here’s an example of using db.collection.insert() to insert multiple documents into a collection called pets:

db.pets.insert([
    { _id: 1, name: "Wag", type: "Dog" },
    { _id: 2, name: "Bark", type: "Dog" },
    { _id: 3, name: "Meow", type: "Cat" }
    ])

Result:

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

The db.collection.insert() method returns an object that contains the status of the insert operation.

The object returned depends on whether a single document was inserted or multiple documents.

• When a single document is inserted, it returns a WriteResult object.
• When an array of documents is inserted, it returns a BulkWriteResult object.

We can see that the above example returned a BulkWriteResult object. This is because we added an array of documents. It would have done this even if the array contained just one element.

Now if we use db.collection.find() to look at the collection, we will see the newly added documents.

db.pets.find()

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog" }
{ "_id" : 2, "name" : "Bark", "type" : "Dog" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }

In this case, our three documents are the only ones in the collection, and so only these documents were returned.

However, if the collection was large, we could use the document IDs to narrow the result to just the documents that we’re interested in.

db.pets.find({_id: {$in: [1,2,3]}})

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog" }
{ "_id" : 2, "name" : "Bark", "type" : "Dog" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }

What if the Collection Doesn’t Exist?

If the collection doesn’t exist, it is created, and the documents are added to it.

If the collection already exists, then the documents are simply added to it (provided their _id values don’t conflict with any existing ones).

When I created this example, the collection didn’t exist, and so the insert operation created it.

The _id Field

The _id field is a unique identifier field in MongoDB.

As demonstrated in the previous example, you can provide your own _id field in the document. If you do, then its value must be unique within the collection. This is because your _id field will be used as the unique identifier of the document.

Here’s an example of inserting a document without providing the _id fields.

db.pets.insert(
    { name: "Bruce", type: "Bat" }
    )

Result:

WriteResult({ "nInserted" : 1 })

Note that in this case the method returns a WriteResult object instead of a BulkWriteResult object. This is because we inserted a single document (and it wasn’t in an array).

Now let’s look at the collection again.

db.pets.find()

Result:

{ "_id" : 1, "name" : "Wag", "type" : "Dog" }
{ "_id" : 2, "name" : "Bark", "type" : "Dog" }
{ "_id" : 3, "name" : "Meow", "type" : "Cat" }
{ "_id" : ObjectId("5fe323d837b49e0faf1af218"), "name" : "Bruce", "type" : "Bat" }

We can see that our new document is included in the collection, and it has an _id field with an automatically generated value.

The ordered Parameter

The db.collection.insert() method also accepts an ordered parameter. This is a boolean parameter with a default value of true.

The ordered parameter specifies whether the insert operation should be ordered or unordered.

If ordered is set to false, documents are inserted in an unordered format and may be reordered by mongod to increase performance.

With ordered inserts, if an error occurs during an insert of one of the documents, MongoDB returns on error without processing the remaining documents in the array.

With unordered inserts, if an error occurs during an insert of one of the documents, MongoDB continues to insert the remaining documents in the array.

More Information

The db.collection.insert() method also accepts a writeConcern argument, which describes the level of acknowledgment requested from MongoDB for write operations.

See the MongoDB documentation for db.collection.insert() for more information.