7.4 Write Concerns, Read Concerns & Retryable Operations
Key Takeaways
- Write Concern controls acknowledgment guarantees: 'w' sets node count (e.g., 'majority'), 'j' mandates on-disk journal sync, and 'wtimeout' bounds replication wait time without rolling back primary writes.
- Read Concern levels ('local', 'available', 'majority', 'linearizable', 'snapshot') control data isolation, with 'majority' guaranteeing data is durable and immune to failover rollback.
- Read Preference modes ('primary', 'primaryPreferred', 'secondary', 'secondaryPreferred', 'nearest') route queries, with 'primary' guaranteeing immediate read-after-write consistency.
- Retryable Writes ('retryWrites=true') automatically retry single-statement writes upon network drops or primary elections using unique session IDs ('lsid') and transaction numbers ('txnNumber').
- Retryable writes require a replica set or sharded cluster with acknowledged write concern ('w > 0') and do not apply to unacknowledged writes or raw commands.
7.4 Write Concerns, Read Concerns & Retryable Operations
In a distributed, multi-node database system like MongoDB, application developers must balance data consistency, durability guarantees, latency, and availability. MongoDB provides a flexible, fine-grained consistency model governed by three core mechanisms:
- Write Concern: Controls the acknowledgment and durability level requested for write operations.
- Read Concern: Controls the isolation level and consistency guarantees of data returned by read operations.
- Read Preference: Controls how client read operations are routed across primary and secondary replica set nodes.
Additionally, modern drivers implement Retryable Writes and Retryable Reads, providing automatic, idempotent recovery from transient network disconnects and primary elections. Mastering these mechanisms is critical for both the MongoDB Associate Developer Exam and enterprise system design.
1. Write Concern Parameters & Durability Guarantees
Write Concern describes the level of acknowledgment requested from MongoDB for a write operation (insertOne, updateOne, deleteMany, etc.) before the driver considers the operation complete.
A Write Concern document contains three parameters:
{ w: <value>, j: <boolean>, wtimeout: <number> }
+---------------------------------------------------------------------------------------------------+
| Write Concern Architecture |
| |
| PRIMARY NODE |
| +-------------------------------+ |
| App Write ======> | In-Memory Cache (WiredTiger) | ---- (j: true) ----> Disk Journal (WAL) |
| +-------------------------------+ |
| | |
| Replication via Oplog Stream |
| | |
| +------------------------+------------------------+ |
| v v |
| SECONDARY NODE 1 SECONDARY NODE 2 |
| +---------------------+ +---------------------+ |
| | In-Memory Cache | | In-Memory Cache | |
| +---------------------+ +---------------------+ |
| |
| * w: 1 -> Acknowledged as soon as Primary memory updates. (Fast; rollback risk) |
| * w: "majority" -> Acknowledged once committed to a majority of voting nodes. (Rollback immune)|
| * j: true -> Acknowledged only after written to disk journal log on Primary. |
| * wtimeout: 5000 -> Aborts client wait after 5s if replication lagging. (Primary WRITE STAYS!) |
+---------------------------------------------------------------------------------------------------+
Parameter 1: w (Acknowledgment Count)
w Value | Acknowledgment Semantics | Durability & Rollback Characteristics |
|---|---|---|
w: 1 | Acknowledged once written to memory of the Primary node. (Default in standalone and unconfigured clusters). | Low latency. Vulnerable to rollback if the primary crashes before replicating the oplog entry to secondaries. |
w: 0 | Unacknowledged write ("fire-and-forget"). The driver sends the socket payload and returns immediately without waiting for server response. | Fastest; dangerous. Ignores write constraint errors (e.g. duplicate keys). Sockets still report network errors. |
w: "majority" | Acknowledged once written to a calculated majority of voting members in the replica set (e.g., 2 of 3, or 3 of 5 nodes). | Recommended standard. Guarantees the write cannot be rolled back during a primary failover election. |
w: <number> | Acknowledged once written to the specified integer count of replica set nodes (e.g., w: 3). | Used in custom multi-datacenter replication topologies. |
Parameter 2: j (Journal Durability)
j: false(Default): The primary acknowledges the write once written to the WiredTiger in-memory cache. The in-memory data will be flushed to the on-disk journal log at the next journal commit interval (typically every 100 ms) or checkpoint (every 60 seconds).j: true: The primary holds acknowledgment until the write has been physically synced to the on-disk journal log (WAL). Guarantees that even if power to the primary server is instantly lost, the write will survive upon reboot.
Parameter 3: wtimeout (Replication Timeout)
wtimeout specifies a time limit (in milliseconds) for w: "majority" or w: > 1 replication acknowledgment. It prevents client operations from blocking indefinitely if secondary nodes fall behind or become partitioned.
CRITICAL EXAM TRAP (The
wtimeoutIllusion): When a write operation throws awtimeouterror (e.g., replication took longer thanwtimeout: 5000), the write operation on the Primary node has already SUCCEEDED and is NOT rolled back! The error only means that the requested number of secondaries did not confirm replication within the specified window. Developers must not blindly retry non-idempotent writes upon receiving awtimeout.
2. Read Concern Levels & Data Isolation
While Write Concern dictates how writes are saved, Read Concern controls the consistency, isolation, and freshness of data returned by read operations.
+---------------------------------------------------------------------------------------------------+
| MongoDB Read Concern Levels |
| |
| 1. "local" (Default on Primary) |
| Returns the node's most recent in-memory data. Does not check majority replication. |
| Risk: Data may be rolled back if an un-replicated primary crashes. |
| |
| 2. "available" (Default on Secondaries in Sharded Clusters) |
| Returns latest data without checking replication; may return orphaned chunks in sharding. |
| |
| 3. "majority" |
| Returns data that has been acknowledged by a majority of voting members. |
| Guarantee: Returned data is durable and CANNOT be rolled back during failover. |
| |
| 4. "linearizable" |
| Primary verifies real-time leadership with quorum before returning read results. |
| Guarantee: Real-time serializable read; prevents stale reads during network split-brain. |
| |
| 5. "snapshot" |
| Used in multi-document ACID transactions. Reads from a globally synchronized snapshot. |
| Guarantee: Snapshot Isolation (SI); zero dirty reads, non-repeatable reads, or phantom reads. |
+---------------------------------------------------------------------------------------------------+
Read Concern Comparison Matrix
| Read Concern Level | Rollback Immune? | Causal Consistency? | Latency Profile | Primary Use Case |
|---|---|---|---|---|
"local" | No | No | Lowest latency | High-throughput reads where dirty reads/rollbacks are acceptable |
"available" | No | No | Lowest latency | Secondary reads in un-sharded clusters; IoT telemetry feeds |
"majority" | Yes | Yes (with client session) | Low (reads from cache timestamp) | Financial ledger reads, inventory checks, user auth |
"linearizable" | Yes | Yes (Strict Serializability) | Higher (requires quorum round-trip) | Critical single-document reads (e.g. distributed lock status) |
"snapshot" | Yes | Yes (Snapshot Isolation) | Moderate | Multi-document ACID transactions (session.startTransaction()) |
3. Read Preference Modes & Routing
Read Preference determines how the driver routes read operations across members of a replica set.
+---------------------------------------------------------------------------------------------------+
| Read Preference Modes |
| |
| [ Client Driver ] |
| | |
| +---> primary (Default) ==========> [ PRIMARY NODE ] (Strong Consistency) |
| | |
| +---> secondary ==================> [ SECONDARY 1 ] or [ SECONDARY 2 ] (Reporting/ETL) |
| | |
| +---> nearest ====================> [ Lowest Network Latency Node ] (Geo-distributed) |
+---------------------------------------------------------------------------------------------------+
The Five Read Preference Modes
primary(Default): All read operations route exclusively to the Primary. Ensures strong consistency and immediate read-after-write visibility. If the primary is unavailable (e.g. during an election), reads fail.primaryPreferred: Reads route to the Primary if available. If the primary is unreachable during failover, reads fall back to Secondary nodes (introducing eventual consistency).secondary: Reads route exclusively to Secondary nodes. Used to offload heavy reporting, analytics, or background ETL from the primary.secondaryPreferred: Reads route to Secondaries; falls back to the Primary only if all secondaries are down.nearest: Reads route to the replica set member with the lowest network ping/latency (Primary or Secondary withinlocalThresholdMS). Ideal for geographically distributed multi-region clusters.
4. Retryable Writes & Retryable Reads
In a distributed replica set, transient network drops, socket timeouts, and primary failover elections (which take 2–5 seconds) can interrupt in-flight operations. In legacy database systems, applications were forced to implement complex, error-prone application-level retry loops.
How Retryable Writes Work (retryWrites=true)
Modern MongoDB drivers enable Retryable Writes by default (retryWrites=true). When a write is issued within a client session:
- The driver assigns each write operation a cryptographically unique Client Session ID (
lsid) and an incrementing Transaction Number (txnNumber). - If the operation fails due to a transient network error or a
NotWritablePrimaryelection error, the driver automatically resends the write to the newly elected Primary node using the exact samelsidandtxnNumber. - The new Primary inspects its internal transaction table. If the operation was already executed before the failover, the Primary simply returns the previous success result without re-executing the write. If it was not executed, the Primary applies the write.
- This guarantees strict idempotency (exactly-once write semantics) without risking duplicate inserts or double increments.
+---------------------------------------------------------------------------------------------------+
| Retryable Writes Architecture |
| |
| Client Driver Old Primary (Failing) New Primary (Elected) |
| | | | |
| | --- insertOne(lsid: 1, txn: 42) --> | (Executes write, crashes before ack) | |
| | X | |
| | <--- TCP Connection Reset --------- | |
| | | |
| | ================= Automatic Driver Retry (Same lsid & txnNumber) =========>| |
| | | |
| | | <--- Checks Transaction Table -------| |
| | | (Recognizes txn 42 executed!) | |
| | <================ Returns Cached Acknowledgment ===========================| |
+---------------------------------------------------------------------------------------------------+
Requirements & Limitations for Retryable Writes:
- Requires a Replica Set or Sharded Cluster: Retryable writes do not function on standalone
mongodinstances. - Requires Acknowledged Write Concern:
wmust not be0(unacknowledged writes cannot be retried). - Supported Operations: Single-document mutations (
insertOne,updateOne,deleteOne,replaceOne,findOneAndUpdate,findOneAndDelete,findOneAndReplace). - Unsupported Operations: Unacknowledged writes (
w: 0), non-idempotent raw database commands, and multi-documentinsertManyorupdateManybatches withordered: falsespanning multiple wire batches.
Retryable Reads (retryReads=true)
Enabled by default in modern drivers (retryReads=true), the driver transparently retries read operations (find, aggregate, countDocuments, distinct) once if a transient network error or server selection failure occurs.
An e-commerce order service executes an insert with write concern '{ w: "majority", wtimeout: 3000 }'. Due to network congestion between data centers, the secondaries fail to acknowledge replication within 3 seconds, and the driver catches a MongoWriteConcernException. What is the status of the order document in the database?
Which Read Concern level ensures that data returned by a query has been committed to a voting majority of replica set nodes, guaranteeing that the returned data can never be rolled back in the event of a primary failover?
A global mobile application has replica set nodes distributed across North America, Europe, and Asia. The engineering team wants user profile read queries in each region to be routed to the local replica set member with the lowest network latency. Which Read Preference mode should be configured?
How does MongoDB's Retryable Writes mechanism ('retryWrites=true') guarantee that retrying an insertOne operation after a network timeout does not insert duplicate documents?