Inserting Multiple Documents with insertMany()

The insertMany() method inserts multiple documents in one operation.

Basic syntax

db.collection.insertMany(
  [document1, document2, document3],
  options
)

The first argument must be an array of documents.

Example: Insert a course catalog

db.courses.insertMany([
  {
    title: "MongoDB Basics",
    level: "beginner",
    durationHours: 8
  },
  {
    title: "MongoDB Aggregation",
    level: "intermediate",
    durationHours: 12
  },
  {
    title: "MongoDB Performance",
    level: "advanced",
    durationHours: 10
  }
]);

MongoDB generates identifiers for documents that do not specify _id.

Ordered inserts

By default, insertMany() uses ordered insertion behavior. If an insert fails, the operation stops attempting later documents after encountering the error, although documents successfully inserted before the error remain inserted.

For example, suppose an array contains three documents and the second document violates a unique constraint. The first may already be inserted, the second fails, and the third may not be attempted under ordered execution.

Ordered execution does not make the entire batch transactional.

Unordered inserts

You can request unordered insertion:

db.courses.insertMany(
  [
    { _id: "course-1", title: "MongoDB Basics" },
    { _id: "course-1", title: "Duplicate ID" },
    { _id: "course-2", title: "Aggregation" }
  ],
  { ordered: false }
);

The duplicate _id causes that document's insertion to fail. MongoDB can continue attempting other documents when ordered is false. The operation still reports errors for failed inserts.

The exact result details depend on the driver or shell and the errors encountered.

Batch size and memory

For large imports, avoid constructing an enormous array in application memory without considering memory limits and operational requirements.

Consider batching, streaming input, retry behavior, and the maximum BSON size of individual documents.

insertMany() is not a replacement for bulkWrite()

insertMany() is designed for inserting documents. bulkWrite() supports a mixture of insert, update, replacement, and delete operations in one bulk request.

Use the appropriate method for the workload and understand its error-handling behavior.

Bulk insertion is not automatically all-or-nothing

Successful inserts can remain even when another document in the same insertMany() operation fails. Use a transaction when an actual multi-document all-or-nothing requirement calls for one and the deployment supports it.

Compare ordered and unordered insertion

db.insertManyDemo.insertMany([
  { _id: 1, name: "Arun" },
  { _id: 2, name: "Meera" },
  { _id: 3, name: "Ravi" }
]);

// Unordered insertion attempts independent documents even if one fails.
// Run this example in a disposable practice collection.
db.insertManyDemo.insertMany(
  [
    { _id: 4, name: "Kavitha" },
    { _id: 4, name: "Duplicate ID" },
    { _id: 5, name: "Divya" }
  ],
  { ordered: false }
);

// Inspect which documents exist after the attempted batch.
db.insertManyDemo.find().sort({ _id: 1 });

💡 The second batch deliberately contains a duplicate identifier. Unordered execution continues attempting eligible operations after the failure. The final query shows the documents that were actually inserted. Duplicate errors must still be handled by the application.

Key Takeaways

insertMany() inserts an array of documents.
Ordered insertion stops attempting later documents after an insertion error.
Unordered insertion can continue attempting documents after individual failures.
A failed batch does not imply that no documents were inserted.
Use bulkWrite() when you need a mixture of CRUD operations in a batch.

Knowledge Check

What is a key difference between ordered and unordered insertMany() operations?