Guide to Using db.collection.insertOne in MongoDB
Understanding db.collection.insertOne() in MongoDB
The db.collection.insertOne() method in MongoDB is used to insert a single document into a collection. It’s an essential operation for adding data to a MongoDB database. This method ensures that the document is stored in the specified collection and assigns it a unique identifier (_id) if one is not provided.
Syntax:
db.collection.insertOne( <document>, { writeConcern: <document> } )
Parameters:
Name | Type | Description |
---|---|---|
document | Document | The document to insert into the collection. Must be a valid JSON object. If no _id field is provided, MongoDB automatically generates one. |
writeConcern | Document (Optional) | Specifies the write concern for the operation, controlling the level of acknowledgment required from MongoDB. Example: { w: "majority", wtimeout: 5000 }. |
Notes:
1. document:
- This is the main input for the operation, defining the data to be stored in the collection.
- MongoDB automatically validates the document format and rejects invalid structures.
2. writeConcern:
- Ensures control over data durability and acknowledgment.
- If omitted, the default write concern of the database is used.
Returns: A document containing
- A boolean acknowledged as true if the operation ran with write concern or false if write concern was disabled.
- A field insertedId with the _id value of the inserted document.
Compatibility:
You can use db.collection.insertOne() for deployments hosted in the following environments:
- MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud.
- MongoDB Enterprise: The subscription-based, self-managed version of MongoDB.
- MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB.
Behaviors:
Collection Creation
If the collection does not exist, then the insertOne() method creates the collection.
_id Field
If the document does not specify an _id field, then mongod will add the _id field and assign a unique ObjectId() for the document before inserting. Most drivers create an ObjectId and insert the _id field, but the mongod will create and populate the _id if the driver or application does not.
If the document contains an _id field, the _id value must be unique within the collection to avoid duplicate key error.
Explainability
insertOne() is not compatible with db.collection.explain().
Error Handling
On error, db.collection.insertOne() throws either a writeError or writeConcernError exception.
Schema Validation Errors
If your collection uses schema validation and has validationAction set to error, inserting an invalid document throws a MongoServerError and db.collection.insertOne() fails.
Transactions
db.collection.insertOne() can be used inside distributed transactions.
Example Usage
Basic Example
Code:
// Insert a document into the 'users' collection
db.users.insertOne({
name: "Kshitij Miriam", // Name field
age: 30, // Age field
email: "[email protected]" // Email field
})
Explanation:
- The users collection is the target collection.
- The document contains three fields: name, age, and email.
- If the operation succeeds, MongoDB returns an acknowledgment with an _id field.
Insert with Custom _id
Code:
// Insert a document with a custom _id
db.users.insertOne({
_id: "user123", // Custom identifier
name: "Kshitij Miriam", // Name field
age: 28 // Age field
})
Explanation:
- A custom _id (user123) is specified.
- MongoDB will not generate a new _id since one is provided.
Insert with Write Concern
Code:
// Insert a document with write concern options
db.users.insertOne(
{
name: "Vilma", // Name field
age: 25 // Age field
},
{
writeConcern: { w: "majority", wtimeout: 5000 } // Write concern options
}
)
Explanation:
- The writeConcern ensures the document is written to the majority of nodes.
- The wtimeout specifies a timeout for the write operation (5000 milliseconds).
Returned Acknowledgment
When db.collection.insertOne() executes successfully, it returns an acknowledgment object:
Code:
{
"acknowledged": true,
"insertedId": ObjectId("648ec7f27d58e0001a3d2b3c")
}
Explanation:
- acknowledged: Indicates the write operation was successful.
- insertedId: The unique _id of the inserted document.
Error Scenarios
Duplicate _id Error
Code:
db.users.insertOne({
_id: "user123",
name: "Duplicate User"
})
Error:
Code:
E11000 duplicate key error collection: test.users index: _id_ dup key: { _id: "user123" }
Reason:
- The _id value user123 already exists in the users collection.
- MongoDB does not allow duplicate _id values.
Invalid Document Structure
Code:
db.users.insertOne("InvalidDocument")
Error:
Code:
TypeError: Document must be a valid JSON object
Reason:
- The argument provided is not a valid JSON object.
Best Practices
1. Schema Design:
- Define a consistent document structure across your collections to avoid data inconsistencies.
2. Indexing:
- Use indexing for fields like _id or frequently queried fields to improve performance.
3. Error Handling:
- Always handle errors in application code to gracefully manage insert failures.
4. Validation Rules:
- Use schema validation at the collection level to enforce data integrity.
It will be nice if you may share this link in any developer community or anywhere else, from where other developers may find this content. Thanks.
https://www.w3resource.com/mongodb/mongodb-db-collection-insertone.php
- Weekly Trends and Language Statistics
- Weekly Trends and Language Statistics