3.3 Document Replacement & Deletion Operations

3.3 Document Replacement & Deletion Operations

While field-level update operators modify selected portions of a document, MongoDB also provides document replacement and deletion primitives. replaceOne() swaps out an entire document while preserving its primary key (_id), while deleteOne() and deleteMany() remove documents based on query filter criteria. Understanding how these operations interact with storage engines, indexes, replication oplogs, and sharded environments is a core competency for developers.

---

1. Document Replacement: replaceOne()

db.collection.replaceOne(filter, replacement, options) completely replaces the existing document matching the query filter with a new replacement document.

db.users.replaceOne(
  { _id: 105 }, // Filter matching the target document
  {
    name: "Taylor Morgan",
    email: "tmorgan@example.com",
    tier: "platinum",
    updatedAt: new Date()
  }, // Replacement document (entire new document body)
  {
    upsert: true,
    writeConcern: { w: "majority", wtimeout: 5000 }
  } // Options document
);

Critical Rules of replaceOne()

1. Preservation of _id: The _id field is immutable in MongoDB. If the replacement document does not specify _id, MongoDB retains the original document's _id. If the replacement document explicitly includes an _id, its value must exactly match the existing document's _id, or MongoDB throws an ImmutableField or duplicate key error.
2. Total Field Overwrite: Any fields in the old document that are omitted from the replacement document are permanently removed. The replacement document completely supplants the old document's state.
3. Prohibition of Update Operators: The replacement argument must consist solely of <field>: <value> pairs. It cannot contain atomic update operators (such as $set, $unset, or $inc).

// ERROR EXAMPLE: Passing $set into replaceOne throws an immediate exception
db.users.replaceOne(
  { _id: 105 },
  { $set: { tier: "platinum" } } // MongoServerError: Replacement document must not contain atomic operators
);

replaceOne() Return Document

{
  acknowledged: true,
  matchedCount: 1,
  modifiedCount: 1,
  upsertedId: null,
  upsertedCount: 0
}

Schema Validation and Sharding Rules for replaceOne()

• JSON Schema Validation: When collection validation rules (validator: { $jsonSchema: ... }) are configured, MongoDB validates the replacement document in its entirety. Because replaceOne() replaces the whole document, the replacement payload must satisfy all required fields specified by the schema validator, regardless of whether validationLevel is set to "strict" or "moderate".
• Sharded Collections: In a sharded cluster, executing replaceOne() requires that the query filter includes an exact equality match on the shard key. If the shard key is omitted from the filter in a sharded collection, MongoDB throws a targeting error.

---

2. Document Deletion Methods: deleteOne() & deleteMany()

MongoDB provides two dedicated methods for deleting documents from a collection:

2.1 deleteOne(filter, options)

Deletes the first document that matches the query filter according to natural storage order or index traversal.

db.orders.deleteOne(
  { orderId: "ORD-8821", status: "CANCELLED" },
  { writeConcern: { w: "majority" } }
);

2.2 deleteMany(filter, options)

Deletes all documents in the collection that satisfy the query filter.

db.sessions.deleteMany(
  { expiresAt: { $lt: new Date() } },
  { writeConcern: { w: 1 } }
);

Deletion Options and Return Document

Both deleteOne() and deleteMany() accept options controlling execution:

• writeConcern: Specifies the acknowledgment level (e.g., { w: "majority", wtimeout: 5000 }).
• collation: Specifies locale-sensitive string matching rules for the filter.
• hint: Specifies an index name or index specification document to force an index scan for the filter.

{
  acknowledged: true,
  deletedCount: 14
}

Exam Trap: Passing an empty filter {} to deleteOne({}) will delete the first document encountered in the collection. Passing an empty filter {} to deleteMany({}) will delete every document in the collection.

---

3. Deep Architectural Comparison: deleteMany({}) vs. db.collection.drop()

When a developer needs to clear an entire collection (for instance, during an environment reset, batch reprocessing, or test cleanup), MongoDB offers two distinct approaches: executing db.collection.deleteMany({}) or invoking db.collection.drop(). Although both result in zero documents in the collection, their underlying architectural behaviors differ drastically across the storage engine, indexing subsystem, replication oplog, and filesystem.

// Approach A: Document-level bulk wipe
db.logs.deleteMany({});

// Approach B: Catalog-level collection drop
db.logs.drop();

Architectural Comparison Matrix

When to Use Which Method in Production

• Use deleteMany({}) when:
  • You must preserve custom indexes and collection configuration (e.g., schema validation rules, collation settings) so that incoming application writes can continue immediately without re-indexing.
  • You are deleting a subset of data matching a filter (e.g., { tenantId: "demo" }).
• Use db.collection.drop() when:
  • You want to wipe an entire large dataset quickly without incurring severe oplog replication lag, CPU spikes, or B-tree lock contention.
  • Note: You must recreate any non-default indexes if your application subsequently writes new data to the collection name.

---

4. replaceOne() vs. updateOne() Summary