Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 70 ยท CRUD: update and delete

Bulk Writes

Send many inserts, updates and deletes in one request with bulkWrite, understand ordered vs unordered errors, and batch large imports.

Imagine importing 50,000 products. The obvious loop calls insertOne or updateOne 50,000 times, and each call is a separate round trip: the request travels to the server, the server answers, and your code waits. Even on a fast network, those waits add up to far more time than the database spends on the actual writes.

A bulk write packs many operations into one request. The server executes them and sends back one summary. In this lesson you will build operation lists for bulkWrite, learn what ordered and unordered mean when something fails, and see how to feed very large imports in batches.

MongoDB cannot run on this site. The mongosh and driver snippets are real and read-only; the runnable examples use a stand-in engine in plain JavaScript that models the behavior (including the result counts and error handling), but it has no network, so "round trips" are counted rather than timed.

Why bulk writes

One request Many operations travel together.
Fewer waits Latency is paid once, not per write.
One summary Counts for inserts, updates, deletes.
1 / 2

The bulkWrite operation list

bulkWrite takes an array of operations. Each operation is an object with one key naming the operation type:

JavaScript
db.products.bulkWrite([
  { insertOne: { document: { sku: "A1", qty: 10 } } },
  { updateOne: { filter: { sku: "B2" }, update: { $inc: { qty: -1 } } } },
  { updateMany: { filter: { qty: 0 }, update: { $set: { soldOut: true } } } },
  { replaceOne: { filter: { sku: "C3" }, replacement: { sku: "C3", qty: 5 } } },
  { deleteOne: { filter: { sku: "OLD1" } } },
  { deleteMany: { filter: { discontinued: true } } }
])

Those six names are the full list: insertOne, updateOne, updateMany, replaceOne, deleteOne, deleteMany. The update and replace operations accept upsert: true, as you saw in Upserts, Replace and findAndModify. All operations in one call target the same collection.

The result is a single summary object:

JavaScript
{
  acknowledged: true,
  insertedCount: 1,
  matchedCount: 3,
  modifiedCount: 3,
  deletedCount: 1,
  upsertedCount: 0,
  insertedIds: { '0': ObjectId("...") },
  upsertedIds: {}
}

The counts add up over all operations. matchedCount counts documents found by update and replace operations, and modifiedCount counts those that actually changed. Newer servers (MongoDB 8.0 and drivers that support it) also offer a client-level bulk write that can touch several collections in one request; the collection-level bulkWrite shown here works everywhere.

insertMany, updateMany and deleteMany all have bulk behavior of their own, but they each do one kind of operation. bulkWrite is for mixing kinds, or for sending many different updates (for example, a different $set for each of 1,000 filters), which updateMany cannot express.

JS A mixed bulk write

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Ordered versus unordered

The second argument to bulkWrite is an options object, and its most important setting is ordered.

JavaScript
db.products.bulkWrite(ops, { ordered: false })
  • ordered: true is the default. The server runs the operations in the order you listed them and stops at the first error. Operations after the failure are not run. Use it when later operations depend on earlier ones, for example "insert this order, then update the stock".
  • ordered: false lets the server run the operations in any order (it may even run groups in parallel) and keep going after errors, reporting every failure at the end. Use it for independent operations, such as importing many unrelated documents. It is usually faster.

An error here means a failed write, such as a duplicate _id or a violation of a unique index, not a filter that matched nothing. When errors happen the driver raises a bulk-write error that includes the list of failed operations (each with its position, index, and an error code like 11000 for duplicate key) and the partial counts of what succeeded. Writes that already succeeded are not rolled back; a bulk write is not a transaction. If you need all-or-nothing behavior, look at Multi-Document Transactions.

JS Ordered stops, unordered continues

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The legacy Bulk API

Before bulkWrite existed, shell scripts built a batch with a bulk builder. You will still see it in older code:

JavaScript
const bulk = db.products.initializeOrderedBulkOp()      // or initializeUnorderedBulkOp()
bulk.insert({ _id: 10, name: "Lamp", qty: 3 })
bulk.find({ name: "Notebook" }).updateOne({ $inc: { qty: 5 } })
bulk.find({ qty: 0 }).remove()                          // delete everything out of stock
bulk.find({ sku: "X-1" }).upsert().replaceOne({ sku: "X-1", qty: 1 })
const result = bulk.execute()                           // nothing is sent until here
printjson(result)                                       // nInserted, nMatched, nModified, nRemoved, nUpserted

The ordered builder sends operations in sequence and stops at the first error, and the unordered builder lets the server run them in any order and report all errors, the same trade-off as ordered: true and ordered: false above. execute() throws a BulkWriteError when anything failed, and its writeErrors array lists each failed operation with its index. Everything the builder does, a bulkWrite list does with insertOne, updateOne, deleteMany and replaceOne entries, so prefer bulkWrite in new code.

Batching large imports

How many operations can you send at once? The server limits one batch to 100,000 operations (the maxWriteBatchSize value the server reports) and one message to about 48 MB. You do not have to split the list yourself in simple cases: the driver divides a big bulkWrite into several batches automatically and merges the results. Still, building a 5-million-element array in memory is a bad idea. Read the source in chunks and send each chunk:

JavaScript
const BATCH = 1000;
let ops = [];
for await (const row of readRows()) {
  ops.push({ updateOne: { filter: { sku: row.sku }, update: { $set: row }, upsert: true } });
  if (ops.length === BATCH) {
    await db.products.bulkWrite(ops, { ordered: false });
    ops = [];
  }
}
if (ops.length > 0) await db.products.bulkWrite(ops, { ordered: false });

A batch of 500 to 5,000 operations is a sensible starting point; measure with your own documents. Larger batches reduce round trips but use more memory and make a single failure report bigger. Note that each operation inside a bulk write still needs an index to find its target quickly: 1,000 updateOne operations on an unindexed field mean 1,000 collection scans.

Also remember that writes can be acknowledged differently (see Read and Write Concerns); one acknowledgment per batch is another reason bulk writes are cheaper.

JS Counting round trips

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How many operation types can one entry of a bulkWrite array describe?

    Each entry is an object with one key (insertOne, updateOne, updateMany, replaceOne, deleteOne or deleteMany). The entries can be mixed freely, but all target the same collection.
  2. 2. What does ordered: true (the default) do when an operation fails?

    Ordered bulk writes stop at the first error. Earlier successful writes are kept, because a bulk write is not a transaction.
  3. 3. You import 100,000 independent documents and a few may be duplicates you want to skip. Which setting fits best?

    Unordered writes continue after errors and report all of them at the end, and are usually faster for independent documents.
  4. 4. Why are bulk writes faster than a loop of single writes?

    The server still performs each write, but the waiting for request and response is shared across the whole batch.

Summary

  • bulkWrite sends a list of insertOne, updateOne, updateMany, replaceOne, deleteOne and deleteMany operations in one request and returns summed counts.
  • Ordered (the default) runs in sequence and stops at the first error; unordered continues and reports all errors.
  • Successful operations are not rolled back on failure; a bulk write is not a transaction.
  • The server limits one batch to 100,000 operations and about 48 MB; drivers split larger lists, but you should stream big imports in chunks.
  • Bulk writes save round trips, but each operation still needs a good index to find its documents.

Next, start transforming data with The Aggregation Pipeline.