Two-phase write protocol and writes without the shard key
Parent: Shard Key Design and Resharding as Cost Levers · Published reference · snapshot 2026-10-30
↓ Facts as markdownall context files
Source-anchored research for Two-phase write protocol and writes without the shard key. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- The resharding guide documents this updateOne/replaceOne selection matrix: a full shard key avoids the two-phase write protocol; without the full key, an _id filter avoids it when upsert is false but uses it when upsert is true; with neither the full key nor _id, the guide says the protocol is used. (low confidence) (verified as of 2026-10-14) [source]
- The resharding guide says deleteOne uses the two-phase protocol when its filter has neither the full shard key nor _id. It lists findAndModify, findOneAndDelete, findOneAndReplace, and findOneAndUpdate as requiring the protocol when their filters lack the full shard key. (low confidence) (verified as of 2026-10-14) [source]
- Two-phase writing is distinct from two-phase commit: SERVER-78407 explains that the single-write-shard commit optimization lets these writes skip two-phase commit because they write to at most one shard. (high confidence) (verified as of 2026-10-30) [source]
- SERVER-88153 records incorrect bulk-write targeting when the single-shard optimization ignored atClusterTime under snapshot transactions; its recorded fix version is 8.0.0-rc0. The ticket does not identify a complete affected-version range. (low confidence) (verified as of 2024-03-25) [source]
Problems, failure modes and limitations
- Missing shard-key targeting can add a broadcast read before the targeted write. MongoDB warns that the two-phase write protocol can significantly reduce performance; the evidence supports a qualitative cost warning, not a universal latency multiplier. (high confidence) [source]
Comparisons and alternatives
- Cost evaluation should include whether application filters remain targeted after a shard-key change. MongoDB explicitly recommends changing filters to use the new key; Alibaba Cloud's own ApsaraDB guidance describes query-routing tradeoffs, including hashed-key range queries that broadcast to shard nodes. This is a workload-specific design tradeoff, not proof that extra shards automatically lower write cost. (medium confidence) [source]
Facts and statements
- The two-phase write protocol reads across candidate shards to choose one with a matching document, then sends the write directly to that shard. The implementation interface says both phases execute using an internal transaction. (high confidence) (verified as of 2026-10-30) [source]
- A partial shard key can narrow the read phase to a subset of shards; therefore, 'without the full shard key' does not invariably mean broadcasting to every shard. (low confidence) (verified as of 2026-10-30) [source]
- After resharding changes a collection's shard key, filters that provide only the old key may incur the two-phase write protocol. MongoDB recommends updating the application to filter on the new shard key for optimal performance. (low confidence) (verified as of 2026-10-14) [source]
- An updateOne upsert can omit the full shard key in MongoDB 8.0 according to both the updateOne reference and Alibaba Cloud's MongoDB 8.0 overview. This establishes support in 8.0, not its first introduction version. (medium confidence) (verified as of 2026-10-14) [source]
- Percona documented non-targeted updateOne and deleteOne support in its own 7.0.2-1 release-candidate notes. This is historical support evidence, not a guarantee that all write variants have identical requirements. (low confidence) (verified as of 2023-10-05) [source]
- SERVER-113344 reproduces unwanted bulkWrite success items with errorsOnly:true on a no-shard-key upsert in 8.0.15, potentially causing driver exceptions despite successful writes. The ticket lists fixes in 8.3.0-rc0 and 8.0.37. (low confidence) (verified as of 2026-10-30) [source]
- Validate the new key against actual workload patterns and monitor application query performance after resharding. Genex gives this operational advice; MongoDB additionally calls for updating affected write filters. (medium confidence) [source]
- Cost implication, inferred from the protocol: broadcast discovery plus transactional coordination creates work beyond a directly targeted write. These sources provide no universal slowdown or dollar-saving factor. (medium confidence) [source]
Children
- Broadcast read and targeted write phases (frontier)
- Single-write-shard transaction commit optimization (frontier)
- _id and upsert routing exceptions (frontier)
- Bulk write without shard key response and snapshot-targeting bugs (frontier)
Frontier under this node: Broadcast read and targeted write phases, Bulk write without shard key response and snapshot-targeting bugs, Single-write-shard transaction commit optimization, _id and upsert routing exceptions