MongoDB insertOne() Method - db.Collection.insertOne()

The MongoDB insertOne() method is used to add a single document to a collection. It adds the document to the specified collection and assigns it a unique _id if one is not provided. This insertOne() method is part of the MongoDB driver for various programming languages and can be used in MongoDB Shell, Node.js, Python and other environments.

• Documents can be inserted with or without an _id; if omitted, MongoDB assigns a unique ObjectId automatically.
• If an _id is provided, it must be unique to avoid duplicate key errors.
• insertOne() may throw writeError or writeConcernError.
• The method also works inside multi-document transactions. 

Syntax: 

db.Collection_name.insertOne(

<document>,

{

    writeConcern: <document>

}

)

Key Terms

• <document>: The document we want to insert. A document is a set of key-value pairs similar to a JSON object.
• writeConcern: If we need to specify a custom write concern (e.g., to ensure the data is written to multiple nodes), you can include this option.

Return Value of insertOne()

The insertOne() method returns the following:

• Acknowledgement: It returns acknowledged: true if the write concern was enabled.
• InsertedId: This field contains the _id value of the inserted document

Examples of MongoDB insertOne()

Let’s go over a few examples to understand how insertOne() works in MongoDB. In the following examples, we are working with:

• Database: gfg
• Collection: student
• Document: No document but, we want to insert in the form of the student name and student marks.

Example 1: Insert a Document without Specifying an _id Field

 Here, we are inserting the document whose name is Akshay and marks is 500 in the student collection. MongoDB will automatically assign a unique _id field to this document.

Query:

db.student.insertOne({Name: "Akshay", Marks: 500})

Output:

Explanation: As shown above, MongoDB has inserted the document with a new ObjectId automatically generated for the _id field.

Example 2: Insert a Document Specifying an _id Field

Here, we are inserting a document whose unique id is Stu102, name is Vishal, and marks is 230 in the student collection

Query:

db.student.insertOne({_id: "Stu102", Name: "Vishal", Marks: 230})

Output:

Explanation: Here, we specified the _id as "Stu102", and MongoDB inserts the document successfully.

Example 3: Handling Write Concern with insertOne()

If we want to specify a custom write concern, we can add an optional writeConcern parameter. For instance, this can be useful when we want to ensure data is written to multiple nodes before considering it committed.

Query:

db.student.insertOne(
  { Name: "John", Marks: 420 },
  { writeConcern: { w: 1, j: true, wtimeout: 5000 } }
)

Common Errors with insertOne()

While the insertOne() method is quite efficient, you might encounter some errors when:

• Duplicate _id: If the _id field is already present in the collection, MongoDB will throw a DuplicateKeyError. Always ensure the _id field is unique unless you’re ok with the default behavior of automatic _id generation.
• Write Concern Errors: If you’ve set a custom write concern and it cannot be satisfied (e.g., not enough replicas), you might get a WriteConcernError.