Chunk migration commit, range deleter and orphan cleanup internals

Parent: Long-running secondary reads in sharded clusters · Published reference · snapshot 2026-10-31

Source-anchored research for Chunk migration commit, range deleter and orphan cleanup internals. 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

In ApsaraDB for MongoDB, receiveChunkWaitForRangeDeleterTimeoutMS controls how long an incoming migration waits for orphan deletion. Alibaba documents ExceededTimeLimit errors when deletion of the incoming range does not finish in time; this is a managed-service setting and must not be assumed identical on every upstream version. (low confidence) (verified as of 2026-09-11) [source]

Comparisons and alternatives

Range deletion consumes CPU, cache and disk I/O. Alibaba documents a tradeoff: smaller deletion batches or longer intervals can reduce resource spikes, but excessive delay prolongs orphan cleanup and can cause overlapping migration timeouts. Its parameter values describe ApsaraDB and should not be assumed to be upstream defaults. (high confidence) [source]
Current cleanupOrphaned documentation describes a command that waits for background cleanup rather than directly deleting documents, and marks it deprecated since 8.0. Do not apply older looping cleanup examples as a description of current range-deleter internals. (low confidence) (verified as of 2026-10-30) [source]
Current cleanupOrphaned semantics wait for automatic orphan cleanup rather than directly deleting documents. The command runs against the shard primary and waits across the namespace regardless of startingFromKey; older range-iteration scripts require version-specific interpretation. (high confidence) (verified as of 2026-10-30) [source]

Facts and statements

Migration commit changes cluster metadata after the recipient catches up with changes made during copying. Donor-side physical deletion follows that ownership change; the balancer can start another migration before the preceding deletion phase finishes. (high confidence) [source]
The balancer can begin another range migration before an earlier donor deletion finishes. Cleanup is asynchronous, and ordinary orphan copies can therefore remain after successful migrations without implying that migration failed. (high confidence) [source]
Under the documented default cleanup sequence, the donor waits for pre-existing primary reads, then waits orphanCleanupDelaySecs, then deletes the orphan range. This creates a delay between ownership transfer and replicated physical deletion; it is not a fixed upper bound on cleanup completion. (high confidence) [source]
Waiting for deletion with the migration's wait-for-delete option bypasses orphanCleanupDelaySecs. Jin's MongoDB 8.0.32 experiment observed zero remaining donor documents for the explicitly waited range while ten earlier delayed cleanup tasks still remained. (high confidence) [source]
A recipient can wait for outstanding deletions that overlap an incoming range, and the wait can time out. Alibaba documents receiveChunkWaitForRangeDeleterTimeoutMS for this condition; Jin independently reproduced the migration timeout and overlap log message in MongoDB 8.0.32. (high confidence) [source]
SERVER-125663 describes an internal pending-to-ready gate: migration commit registers an in-memory deletion task and removes pending from the durable config.rangeDeletions document; an operation observer calls clearPending() to unblock deletion. Its reported race drops that collection first, causing NoMatchingDocument and leaving the in-memory deletion chain stalled. (low confidence) [source]
SERVER-91970 records why range-deletion bookkeeping must account for overlapping donor tasks as well as recipient tasks: interrupted migration recovery can race with immediately migrating the newly received range onward and marking the wrong pending task ready. The issue identifies fixes in 7.0.13, 8.0.0-rc14 and 8.1.0-rc0. (low confidence) [source]
The shard-local config.rangeDeletions collection stores persistent range-deletion tasks identified by collection UUID and a half-open shard-key interval [min, max). The pending flag means a range is not yet ready for deletion. (low confidence) (verified as of 2026-10-30) [source]
At migration start, donor and recipient each create a pending deletion task. Commit readies the donor task and deletes the recipient task; abort deletes the donor task and readies the recipient task, cleaning up the unsuccessful copy. (low confidence) (verified as of 2026-10-30) [source]
The range deleter runs on shard primaries and waits for local reads retaining a range to drain. It exposes a completion future that resolves only after every deletion task overlapping the requested range completes. (low confidence) (verified as of 2026-10-30) [source]
Step-down stops range cleanup and clears in-memory service state. Step-up asynchronously rebuilds registrations from persisted tasks, temporarily excluding writes to config.rangeDeletions during recovery; persisted state permits cleanup to survive primary crashes and restarts. (high confidence) (verified as of 2026-10-30) [source]
Range migration uses majority acknowledgment at specific transition points independently of _secondaryThrottle. Before further outgoing cleanup or new incoming migrations proceed, cleanup writes from a completed outgoing migration must have replicated to a majority. (low confidence) [source]
Range deletion can produce substantial CPU, cache and disk-I/O load. rangeDeleterBatchSize limits documents per batch, while rangeDeleterBatchDelayMS spaces deletion batches; larger delays trade lower instantaneous pressure for a longer cleanup backlog. (high confidence) [source]
Idle cursors can prevent cleanup from completing. Alibaba documents the diagnostic message "will be scheduled after all possibly dependent queries finish" and inspecting $currentOp with idleCursors enabled to identify retained cursors. (high confidence) (verified as of 2026-09-23) [source]
Orphan copies can affect tools that read each shard directly. Huawei documents that its DRS full extraction includes both owned and orphaned documents and that an Ignore conflict policy can preserve whichever copy arrives first, causing inconsistent migration results. (low confidence) (verified as of 2025-06-03) [source]

Children

Range deletion task persistence and pending-to-ready transitions (frontier)
Overlapping range deletion and migration admission (frontier)
Range deletion batching and resource contention (frontier)
Pinned migration-recipient retry backoff and recovery boundaries

Frontier under this node: Overlapping range deletion and migration admission, Range deletion batching and resource contention, Range deletion task persistence and pending-to-ready transitions

← the whole tree · 3D view· how to read this page