Inserting a Single Document with insertOne()

The insertOne() method inserts a single document into a collection.

Basic syntax

db.collection.insertOne(document, options)

The options argument is optional. Supported options depend on the operation and MongoDB version.

Example 1: Insert a student

db.students.insertOne({
  name: "Arun",
  age: 22,
  course: "MongoDB",
  active: true
});

If _id is omitted, MongoDB's driver or shell ordinarily generates an ObjectId for the inserted document.

The insert result includes the inserted identifier.

Example 2: Insert nested documents

db.students.insertOne({
  name: "Meera",
  age: 24,
  address: {
    city: "Chennai",
    country: "India"
  },
  skills: ["JavaScript", "Node.js", "MongoDB"]
});

MongoDB stores address as an embedded document and skills as an array.

Example 3: Supply a custom _id

db.students.insertOne({
  _id: "student-1001",
  name: "Ravi",
  age: 25
});

The _id field does not have to be an ObjectId. It must be unique within the collection.

If another document already has the same _id, the insert fails with a duplicate-key error.

Example 4: Inspect the insert result

const result = db.students.insertOne({
  name: "Kavitha",
  age: 21
});

printjson(result);

The result typically contains acknowledged: true and insertedId.

An acknowledged write indicates that the server acknowledged the operation according to the configured write concern. It should not be confused with a guarantee that every possible downstream system has processed the data.

Example 5: Insert an explicitly typed value

db.products.insertOne({
  name: "Keyboard",
  price: NumberDecimal("2499.99"),
  createdAt: new Date()
});

This example stores the price as Decimal128 and the creation time as BSON Date.

Practical considerations

Validate required fields before inserting data.
Avoid hardcoding production identifiers unless the application requires deterministic IDs.
Use a consistent field naming convention.
Store values using appropriate BSON types.
Handle duplicate-key and validation errors in the application.
Never assume an insert succeeded solely because the application sent the request.

Use the inserted identifier

When a new document is inserted, use the returned insertedId to retrieve or reference that document rather than relying on a non-unique field such as a person's name.

Insert a document and inspect the result

const result = db.students.insertOne({
  name: "Arun",
  age: NumberInt(22),
  course: "MongoDB",
  skills: ["JavaScript", "MongoDB"],
  createdAt: new Date()
});

print("Acknowledged:", result.acknowledged);
print("Inserted ID:", result.insertedId);

db.students.findOne({ _id: result.insertedId });

💡 The example inserts a document, inspects the acknowledged write result and generated identifier, and retrieves the inserted document by its identifier.

Key Takeaways

insertOne() inserts one document.
MongoDB ordinarily generates an ObjectId when _id is omitted.
Custom _id values are supported when unique within the collection.
Duplicate identifiers cause duplicate-key errors.
The insert result exposes the inserted identifier and write acknowledgment status.

Knowledge Check

What happens if insertOne() attempts to insert a document with an _id already present in the collection?