<section>
 <h1 class="contains-headerlink leafygreen-ui-41fr9s" weight="medium">
  Sharded Cluster Balancer
  <a class="headerlink leafygreen-ui-1kepx47" href="#sharded-cluster-balancer" title="Permalink to this heading">
   <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
    <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
    </path>
    <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
    </path>
   </svg>
   <div class="css-1btu0w3 evvkmar0" id="sharded-cluster-balancer">
   </div>
  </a>
 </h1>
 <div class="leafygreen-ui-a5yxub">
  <p class="css-1cmx2d4 ef7gu8j0">
   On this page
  </p>
  <ul class="css-1qb0mst ef7gu8j1">
   <li class="leafygreen-ui-1e7a0ei">
    <a class="lg-ui-0001 leafygreen-ui-e98ikf" href="#balancer-internals" target="_self">
     <span>
      Balancer Internals
     </span>
    </a>
   </li>
   <li class="leafygreen-ui-1jqtqlb">
    <a class="lg-ui-0001 leafygreen-ui-cpmeq5" href="#range-migration-procedure" target="_self">
     <span>
      Range Migration Procedure
     </span>
    </a>
   </li>
   <li class="leafygreen-ui-1jqtqlb">
    <a class="lg-ui-0001 leafygreen-ui-cpmeq5" href="#shard-size" target="_self">
     <span>
      Shard Size
     </span>
    </a>
   </li>
   <li class="leafygreen-ui-1jqtqlb">
    <a class="lg-ui-0001 leafygreen-ui-cpmeq5" href="#chunk-size-and-balancing" target="_self">
     <span>
      Chunk Size and Balancing
     </span>
    </a>
   </li>
  </ul>
 </div>
 <p class="leafygreen-ui-1kp3ins">
  The MongoDB balancer is a background process that monitors the amount of
data on each
  <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/glossary/#std-term-shard">
   shard
  </a>
  for each sharded collection. When the amount
of data for a sharded collection on a given shard reaches specific
  <a class="lg-ui-0001 leafygreen-ui-fgcsv5" href="#std-label-sharding-migration-thresholds" target="_self">
   <span>
    migration thresholds
   </span>
  </a>
  , the balancer
attempts to automatically migrate data between shards and reach an even
amount of data per shard while respecting the
  <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/zone-sharding/#std-label-zone-sharding">
   zones
  </a>
  . By default, the balancer process is always enabled.
 </p>
 <p class="leafygreen-ui-1kp3ins">
  The balancing procedure for
  <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/glossary/#std-term-sharded-cluster">
   sharded clusters
  </a>
  is entirely transparent to the user and application layer, though there
may be some performance impact while the procedure takes place.
 </p>
 <div class="figure css-5vkxs0" style="width:700px">
  <img alt="Diagram of a collection distributed across three shards. For this collection, the difference in the number of chunks between the shards reaches the *migration thresholds* (in this case, 2) and triggers migration." class="leafygreen-ui-1qnf57e" height="180" src="/docs/manual/images/sharding-migrating.bakedsvg.svg" style="--border-color:#C1C7C6" width="500"/>
 </div>
 <p class="leafygreen-ui-1kp3ins">
  The balancer runs on the primary of the config server replica set
(CSRS).
 </p>
 <p class="leafygreen-ui-1kp3ins">
  To configure collection balancing for a single collection, see
  <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/configureCollectionBalancing/#mongodb-dbcommand-dbcmd.configureCollectionBalancing">
   <code class="leafygreen-ui-1l06pbn">
    configureCollectionBalancing
   </code>
   .
  </a>
 </p>
 <p class="leafygreen-ui-1kp3ins">
  To manage the sharded cluster balancer, see
  <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-sharded-cluster-balancer">
   Manage Sharded Cluster Balancer
   <!-- -->
   .
  </a>
 </p>
 <span class="leafygreen-ui-1qnjd6d" id="std-label-sharding-balancing-internals">
 </span>
 <span class="leafygreen-ui-1qnjd6d" id="std-label-sharding-internals-balancing">
 </span>
 <section>
  <h2 class="contains-headerlink leafygreen-ui-19f71ei" weight="medium">
   Balancer Internals
   <a class="headerlink leafygreen-ui-1kepx47" href="#balancer-internals" title="Permalink to this heading">
    <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
     <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
     </path>
     <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
     </path>
    </svg>
    <div class="css-1btu0w3 evvkmar0" id="balancer-internals">
    </div>
   </a>
  </h2>
  <p class="leafygreen-ui-1kp3ins">
   Range migrations carry some overhead in terms of bandwidth and
workload, both of which can impact database performance.
The
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/glossary/#std-term-balancer">
    balancer
   </a>
   attempts to minimize the impact by:
  </p>
  <ul class="leafygreen-ui-rioki0">
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     Restricting a shard to at most one migration at any given time.
Specifically, a shard cannot participate in multiple data migrations
at the same time. The balancer migrates ranges one at a time.
    </p>
    <p class="leafygreen-ui-1kp3ins">
     MongoDB can perform parallel data migrations, but a shard can
participate in at most one migration at a time. For a sharded cluster
with
     <em>
      n
     </em>
     shards, MongoDB can perform at most
     <em>
      n/2
     </em>
     (rounded down)
simultaneous migrations.
    </p>
    <p class="leafygreen-ui-1kp3ins">
     See also
     <a class="lg-ui-0001 leafygreen-ui-fgcsv5" href="#std-label-range-migration-queuing" target="_self">
      <span>
       Asynchronous Range Migration Cleanup
       <!-- -->
       .
      </span>
     </a>
    </p>
   </li>
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     Starting a balancing round only when the
     <strong>
      difference in the amount
of data
     </strong>
     between the shard with the most data for a sharded collection
and the shard with the least data for that collection reaches the
     <a class="lg-ui-0001 leafygreen-ui-fgcsv5" href="#std-label-sharding-migration-thresholds" target="_self">
      <span>
       migration threshold
       <!-- -->
       .
      </span>
     </a>
    </p>
   </li>
  </ul>
  <p class="leafygreen-ui-1kp3ins">
   You can disable the balancer temporarily for maintenance, but leaving
the balancer disabled for extended periods of time can degrade cluster
performance. For more information, see
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-sharding-balancing-disable-temporally">
    Disable the Balancer
    <!-- -->
    .
   </a>
  </p>
  <p class="leafygreen-ui-1kp3ins">
   You can also limit the window during which the balancer runs to prevent
it from impacting production traffic. See
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-sharding-schedule-balancing-window">
    Schedule the Balancing
Window
   </a>
   for details.
  </p>
  <div class="leafygreen-ui-15mdk4" role="note">
   <h2 class="leafygreen-ui-6n7b7d">
    Note
   </h2>
   <div class="leafygreen-ui-9mycqc">
    <p class="leafygreen-ui-1kp3ins">
     The specification of the balancing window is relative to the local
time zone of the primary of the config server replica set.
    </p>
   </div>
  </div>
  <div class="leafygreen-ui-13vw3ie" role="note">
   <h2 class="leafygreen-ui-1fn4p2b">
    Tip
   </h2>
   <h3 class="leafygreen-ui-144d5kf">
    <strong>
     See also:
    </strong>
   </h3>
   <div class="leafygreen-ui-9mycqc">
    <p class="leafygreen-ui-1kp3ins">
     <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-sharded-cluster-balancer">
      Manage Sharded Cluster Balancer
     </a>
    </p>
   </div>
  </div>
  <section>
   <h3 class="contains-headerlink leafygreen-ui-15ajumo" weight="medium">
    Adding and Removing Shards from the Cluster
    <a class="headerlink leafygreen-ui-1kepx47" href="#adding-and-removing-shards-from-the-cluster" title="Permalink to this heading">
     <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
      <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
      </path>
      <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
      </path>
     </svg>
     <div class="css-1btu0w3 evvkmar0" id="adding-and-removing-shards-from-the-cluster">
     </div>
    </a>
   </h3>
   <p class="leafygreen-ui-1kp3ins">
    Adding a shard to a cluster creates an imbalance, since the new
shard has no data. While MongoDB begins migrating data to the new
shard immediately, it can take some time before the cluster balances.
See the
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/add-shards-to-shard-cluster/#std-label-sharding-procedure-add-shard">
     Add Shards to a Cluster
    </a>
    tutorial for instructions on adding a shard to a cluster.
   </p>
   <div class="leafygreen-ui-13vw3ie" role="note">
    <h2 class="leafygreen-ui-1fn4p2b">
     Tip
    </h2>
    <div class="leafygreen-ui-9mycqc">
     <p class="leafygreen-ui-1kp3ins">
      If your application meets the
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/sharding-reshard-a-collection/#std-label-reshard-requirements">
       Before you Begin
      </a>
      , you can use the
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/reshardCollection/#mongodb-dbcommand-dbcmd.reshardCollection">
       <code class="leafygreen-ui-1l06pbn">
        reshardCollection
       </code>
      </a>
      command to redistribute data across the
cluster to include the new shards.  This process is much faster than the
alternative
      <a class="lg-ui-0001 leafygreen-ui-fgcsv5" href="#std-label-range-migration-procedure" target="_self">
       <span>
        Range Migration Procedure
        <!-- -->
        .
       </span>
      </a>
     </p>
     <p class="leafygreen-ui-1kp3ins">
      For an example, see
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/reshardCollection/#std-label-reshardCollection-redistribute-data">
       Redistribute Data to New Shards
       <!-- -->
       .
      </a>
     </p>
    </div>
   </div>
   <p class="leafygreen-ui-1kp3ins">
    Removing a shard from a cluster creates a similar imbalance, since data
residing on that shard must be redistributed throughout the cluster.
While MongoDB begins draining a removed shard immediately, it can take
some time before the cluster balances.
    <em>
     Do not
    </em>
    shutdown the servers
associated to the removed shard during this process.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    When you remove a shard in a cluster with an uneven chunk
distribution, the balancer first removes the chunks from the draining
shard and then balances the remaining uneven chunk distribution.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    See the
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/remove-shards-from-cluster/#std-label-remove-shards-from-cluster-tutorial">
     Remove Shards from a Cluster
    </a>
    tutorial for instructions on
safely removing a shard from a cluster.
   </p>
   <div class="leafygreen-ui-13vw3ie" role="note">
    <h2 class="leafygreen-ui-1fn4p2b">
     Tip
    </h2>
    <h3 class="leafygreen-ui-144d5kf">
     <strong>
      See also:
     </strong>
    </h3>
    <div class="leafygreen-ui-9mycqc">
     <p class="leafygreen-ui-1kp3ins">
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/sh.balancerCollectionStatus/#mongodb-method-sh.balancerCollectionStatus">
       <code class="leafygreen-ui-1l06pbn">
        sh.balancerCollectionStatus()
       </code>
      </a>
     </p>
    </div>
   </div>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-chunk-migration-procedure">
   </span>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-range-migration-procedure">
   </span>
  </section>
 </section>
 <section>
  <h2 class="contains-headerlink leafygreen-ui-19f71ei" weight="medium">
   Range Migration Procedure
   <a class="headerlink leafygreen-ui-1kepx47" href="#range-migration-procedure" title="Permalink to this heading">
    <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
     <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
     </path>
     <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
     </path>
    </svg>
    <div class="css-1btu0w3 evvkmar0" id="range-migration-procedure">
    </div>
   </a>
  </h2>
  <p class="leafygreen-ui-1kp3ins">
   All range migrations use the following procedure:
  </p>
  <ol class="leafygreen-ui-rioki0" type="1">
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     The balancer process sends the
     <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/moveRange/#mongodb-dbcommand-dbcmd.moveRange">
      <code class="leafygreen-ui-1l06pbn">
       moveRange
      </code>
     </a>
     command to
the source shard.
    </p>
   </li>
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     The source starts the move when it receives an internal
     <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/moveRange/#mongodb-dbcommand-dbcmd.moveRange">
      <code class="leafygreen-ui-1l06pbn">
       moveRange
      </code>
     </a>
     command. During the migration process,
operations to the range are sent to the source shard. The source
shard is responsible for incoming write operations for the range.
    </p>
   </li>
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     The destination shard builds any indexes required by the source
that do not exist on the destination.
    </p>
   </li>
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     The destination shard begins requesting documents in the range and
starts receiving copies of the data. See also
     <a class="lg-ui-0001 leafygreen-ui-fgcsv5" href="#std-label-range-migration-replication" target="_self">
      <span>
       Range Migration and Replication
       <!-- -->
       .
      </span>
     </a>
    </p>
   </li>
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     After receiving the final document in the range, the
destination shard starts a synchronization process to ensure that it
has the changes to the migrated documents that occurred during the
migration.
    </p>
   </li>
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     When fully synchronized, the source shard connects to the
     <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/glossary/#std-term-config-database">
      config database
     </a>
     and updates the cluster metadata with the new
location for the range.
    </p>
   </li>
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     After the source shard completes the update of the metadata,
and once there are no open cursors on the range, the source shard
deletes its copy of the documents.
    </p>
    <div class="leafygreen-ui-15mdk4" role="note">
     <h2 class="leafygreen-ui-6n7b7d">
      Note
     </h2>
     <div class="leafygreen-ui-9mycqc">
      <p class="leafygreen-ui-1kp3ins">
       If the balancer needs to perform additional chunk migrations from
the source shard, the balancer can start the next chunk migration
without waiting for the current migration process to finish this
deletion step. See
       <a class="lg-ui-0001 leafygreen-ui-fgcsv5" href="#std-label-chunk-migration-queuing" target="_self">
        <span>
         Asynchronous Range Migration Cleanup
         <!-- -->
         .
        </span>
       </a>
      </p>
     </div>
    </div>
   </li>
  </ol>
  <div class="leafygreen-ui-1sjx7ru" role="note">
   <h2 class="leafygreen-ui-29m78u">
    Warning
   </h2>
   <h3 class="leafygreen-ui-144d5kf">
    <strong>
     Secondary Reads in a Sharded Cluster with Migrations Can Miss Documents
    </strong>
   </h3>
   <div class="leafygreen-ui-9mycqc">
    <p class="leafygreen-ui-1kp3ins">
     Long-running secondary reads in a sharded cluster can miss documents
if migrations are occurring.
    </p>
    <p class="leafygreen-ui-1kp3ins">
     Before deleting a chunk during chunk migration, MongoDB waits for
     <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/parameters/#mongodb-parameter-param.orphanCleanupDelaySecs">
      <code class="leafygreen-ui-1l06pbn">
       orphanCleanupDelaySecs
      </code>
     </a>
     , or for in-progress queries
involving the chunk to complete on the shard primary, whichever is
longer. Queries that were initially run on a node that was primary,
but continue after the node has stepped down to a secondary, will be
treated as if they were initially executed on a secondary. That is,
the server only waits for
     <code class="leafygreen-ui-1l06pbn">
      orphanDelayCleanupSecs
     </code>
     if there are no
queries targeting the chunk on the current primary.
    </p>
    <p class="leafygreen-ui-1kp3ins">
     Queries that target the chunk and are run on secondaries may miss
documents if these queries take longer than
     <code class="leafygreen-ui-1l06pbn">
      orphanCleanupDelaySecs
     </code>
     .
    </p>
   </div>
  </div>
  <div class="leafygreen-ui-13vw3ie" role="note">
   <h2 class="leafygreen-ui-1fn4p2b">
    Tip
   </h2>
   <h3 class="leafygreen-ui-144d5kf">
    <strong>
     See also:
    </strong>
   </h3>
   <div class="leafygreen-ui-9mycqc">
    <p class="leafygreen-ui-1kp3ins">
     <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/serverStatus/#mongodb-serverstatus-serverstatus.shardingStatistics.countDonorMoveChunkLockTimeout">
      <code class="leafygreen-ui-1l06pbn">
       shardingStatistics.countDonorMoveChunkLockTimeout
      </code>
     </a>
    </p>
   </div>
  </div>
  <span class="leafygreen-ui-1qnjd6d" id="std-label-sharding-migration-thresholds">
  </span>
  <section>
   <h3 class="contains-headerlink leafygreen-ui-15ajumo" weight="medium">
    Migration Thresholds
    <a class="headerlink leafygreen-ui-1kepx47" href="#migration-thresholds" title="Permalink to this heading">
     <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
      <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
      </path>
      <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
      </path>
     </svg>
     <div class="css-1btu0w3 evvkmar0" id="migration-thresholds">
     </div>
    </a>
   </h3>
   <p class="leafygreen-ui-1kp3ins">
    To minimize the impact of balancing on the cluster, the
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/glossary/#std-term-balancer">
     balancer
    </a>
    only begins balancing after the distribution of
data for a sharded collection has reached certain thresholds.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    A collection is considered balanced if the difference in data between
shards (for that collection) is less than three times the configured
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/modify-chunk-size-in-sharded-cluster/#std-label-tutorial-modifying-range-size">
     range size
    </a>
    for the collection.
For the default range size of
    <code class="leafygreen-ui-1l06pbn">
     128MB
    </code>
    , two shards must have a data
size difference for a given collection of at least
    <code class="leafygreen-ui-1l06pbn">
     384MB
    </code>
    for a
migration to occur.
   </p>
   <div class="leafygreen-ui-13vw3ie" role="note">
    <h2 class="leafygreen-ui-1fn4p2b">
     Tip
    </h2>
    <h3 class="leafygreen-ui-144d5kf">
     <strong>
      See also:
     </strong>
    </h3>
    <div class="leafygreen-ui-9mycqc">
     <p class="leafygreen-ui-1kp3ins">
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/sh.balancerCollectionStatus/#mongodb-method-sh.balancerCollectionStatus">
       <code class="leafygreen-ui-1l06pbn">
        sh.balancerCollectionStatus()
       </code>
      </a>
     </p>
    </div>
   </div>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-chunk-migration-queuing">
   </span>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-range-migration-queuing">
   </span>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-asynchronous-chunk-migration-cleanup">
   </span>
  </section>
  <section>
   <h3 class="contains-headerlink leafygreen-ui-15ajumo" weight="medium">
    Asynchronous Range Migration Cleanup
    <a class="headerlink leafygreen-ui-1kepx47" href="#asynchronous-range-migration-cleanup" title="Permalink to this heading">
     <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
      <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
      </path>
      <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
      </path>
     </svg>
     <div class="css-1btu0w3 evvkmar0" id="asynchronous-range-migration-cleanup">
     </div>
    </a>
   </h3>
   <p class="leafygreen-ui-1kp3ins">
    To migrate data from a shard, the balancer migrates the
data one range at a time. However, the balancer does not wait for the
current migration's delete phase to complete before starting the next
range migration. See
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/sharding-data-partitioning/#std-label-sharding-range-migration">
     Range Migration
    </a>
    for the range
migration process and the delete phase.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    This queuing behavior allows shards to unload data more quickly in
cases of heavily imbalanced cluster, such as when performing initial
data loads without pre-splitting and when adding new shards.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    This behavior also affects the
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/moveRange/#mongodb-dbcommand-dbcmd.moveRange">
     <code class="leafygreen-ui-1l06pbn">
      moveRange
     </code>
    </a>
    command, and
migration scripts that use the
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/moveRange/#mongodb-dbcommand-dbcmd.moveRange">
     <code class="leafygreen-ui-1l06pbn">
      moveRange
     </code>
    </a>
    command may
proceed more quickly.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    In some cases, the delete phases may persist longer. Range migrations
are enhanced to be more resilient in the event of a failover during the
delete phase. Orphaned documents are cleaned up even if a replica set's
primary crashes or restarts during this phase.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    The
    <code class="leafygreen-ui-1l06pbn">
     _waitForDelete
    </code>
    balancer setting can alter the behavior so that
the delete phase of the current migration blocks the start of the next
chunk migration. The
    <code class="leafygreen-ui-1l06pbn">
     _waitForDelete
    </code>
    is generally for internal
testing purposes. For more information, see
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-wait-for-delete-setting">
     Wait for Delete
     <!-- -->
     .
    </a>
   </p>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-chunk-migration-replication">
   </span>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-range-migration-replication">
   </span>
  </section>
  <section>
   <h3 class="contains-headerlink leafygreen-ui-15ajumo" weight="medium">
    Range Migration and Replication
    <a class="headerlink leafygreen-ui-1kepx47" href="#range-migration-and-replication" title="Permalink to this heading">
     <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
      <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
      </path>
      <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
      </path>
     </svg>
     <div class="css-1btu0w3 evvkmar0" id="range-migration-and-replication">
     </div>
    </a>
   </h3>
   <p class="leafygreen-ui-1kp3ins">
    During range migration, the
    <code class="leafygreen-ui-1l06pbn">
     _secondaryThrottle
    </code>
    value determines
when the migration proceeds with next document in the range.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    In the
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/config-database/#mongodb-data-config.settings">
     <code class="leafygreen-ui-1l06pbn">
      config.settings
     </code>
    </a>
    collection:
   </p>
   <ul class="leafygreen-ui-rioki0">
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      If the
      <code class="leafygreen-ui-1l06pbn">
       _secondaryThrottle
      </code>
      setting for the balancer is set to a
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/glossary/#std-term-write-concern">
       write concern
      </a>
      , each document moved during range migration must receive
the requested acknowledgment before proceeding with the next
document.
     </p>
    </li>
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      If the
      <code class="leafygreen-ui-1l06pbn">
       _secondaryThrottle
      </code>
      setting is unset, the migration process
does not wait for replication to a secondary and instead continues
with the next document.
     </p>
    </li>
   </ul>
   <p class="leafygreen-ui-1kp3ins">
    To update the
    <code class="leafygreen-ui-1l06pbn">
     _secondaryThrottle
    </code>
    parameter for the balancer, see
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-sharded-cluster-config-secondary-throttle">
     Secondary Throttle
    </a>
    for an example.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    Independent of any
    <code class="leafygreen-ui-1l06pbn">
     _secondaryThrottle
    </code>
    setting, certain phases of
the range migration have the following replication policy:
   </p>
   <ul class="leafygreen-ui-rioki0">
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      MongoDB briefly pauses all application reads and writes to the
collection being migrated to on the source shard before updating the
config servers with the range location. MongoDB resumes application
reads and writes after the update. The range move requires all writes
to be acknowledged by majority of the members of the replica set both
before and after committing the range move to config servers.
     </p>
    </li>
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      When an outgoing migration finishes and cleanup occurs, all
writes must be replicated to a majority of servers before further
cleanup (from other outgoing migrations) or new incoming migrations
can proceed.
     </p>
    </li>
   </ul>
   <p class="leafygreen-ui-1kp3ins">
    To update the
    <code class="leafygreen-ui-1l06pbn">
     _secondaryThrottle
    </code>
    setting in the
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/config-database/#mongodb-data-config.settings">
     <code class="leafygreen-ui-1l06pbn">
      config.settings
     </code>
    </a>
    collection, see
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-sharded-cluster-config-secondary-throttle">
     Secondary Throttle
    </a>
    for an example.
   </p>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-migration-chunk-size-limit">
   </span>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-migration-range-size-limit">
   </span>
  </section>
  <section>
   <h3 class="contains-headerlink leafygreen-ui-15ajumo" weight="medium">
    Maximum Number of Documents Per Range to Migrate
    <a class="headerlink leafygreen-ui-1kepx47" href="#maximum-number-of-documents-per-range-to-migrate" title="Permalink to this heading">
     <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
      <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
      </path>
      <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
      </path>
     </svg>
     <div class="css-1btu0w3 evvkmar0" id="maximum-number-of-documents-per-range-to-migrate">
     </div>
    </a>
   </h3>
   <p class="leafygreen-ui-1kp3ins">
    By default, MongoDB cannot move a range if the number of documents in
the range is greater than 2 times the result of dividing the
configured
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/sharding-data-partitioning/#std-label-sharding-range-size">
     range size
    </a>
    by the average
document size. If MongoDB can move a sub-range of a chunk and reduce the
size to less than that, the balancer does so by migrating a range.
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/db.collection.stats/#mongodb-method-db.collection.stats">
     <code class="leafygreen-ui-1l06pbn">
      db.collection.stats()
     </code>
    </a>
    includes the
    <code class="leafygreen-ui-1l06pbn">
     avgObjSize
    </code>
    field,
which represents the average document size in the collection.
   </p>
   <p class="leafygreen-ui-1kp3ins">
    For chunks that are
    <a class="lg-ui-0001 leafygreen-ui-fgcsv5" href="#std-label-migration-chunk-size-limit" target="_self">
     <span>
      too large to migrate
      <!-- -->
      :
     </span>
    </a>
   </p>
   <ul class="leafygreen-ui-rioki0">
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      The balancer setting
      <code class="leafygreen-ui-1l06pbn">
       attemptToBalanceJumboChunks
      </code>
      allows the
balancer to migrate chunks too large to move as long as the chunks
are not labeled
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/sharding-data-partitioning/#std-label-jumbo-chunk">
       jumbo
      </a>
      . See
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-balance-chunks-that-exceed-size-limit">
       Balance Ranges that Exceed Size Limit
      </a>
      for details.
     </p>
     <p class="leafygreen-ui-1kp3ins">
      When issuing
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/moveRange/#mongodb-dbcommand-dbcmd.moveRange">
       <code class="leafygreen-ui-1l06pbn">
        moveRange
       </code>
      </a>
      and
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/moveChunk/#mongodb-dbcommand-dbcmd.moveChunk">
       <code class="leafygreen-ui-1l06pbn">
        moveChunk
       </code>
      </a>
      commands, it's possible to specify the
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/moveRange/#std-label-moverange-forceJumbo">
       forceJumbo
      </a>
      option to allow for the migration of ranges
that are too large to move. The ranges may or may not be labeled
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/sharding-data-partitioning/#std-label-jumbo-chunk">
       jumbo
       <!-- -->
       .
      </a>
     </p>
    </li>
   </ul>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-range-deletion-performance-tuning">
   </span>
  </section>
  <section>
   <h3 class="contains-headerlink leafygreen-ui-15ajumo" weight="medium">
    Range Deletion Performance Tuning
    <a class="headerlink leafygreen-ui-1kepx47" href="#range-deletion-performance-tuning" title="Permalink to this heading">
     <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
      <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
      </path>
      <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
      </path>
     </svg>
     <div class="css-1btu0w3 evvkmar0" id="range-deletion-performance-tuning">
     </div>
    </a>
   </h3>
   <p class="leafygreen-ui-1kp3ins">
    You can tune the performance impact of range deletions
with
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/parameters/#mongodb-parameter-param.rangeDeleterBatchSize">
     <code class="leafygreen-ui-1l06pbn">
      rangeDeleterBatchSize
     </code>
    </a>
    ,
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/parameters/#mongodb-parameter-param.rangeDeleterBatchDelayMS">
     <code class="leafygreen-ui-1l06pbn">
      rangeDeleterBatchDelayMS
     </code>
    </a>
    , and
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/parameters/#mongodb-parameter-param.rangeDeleterHighPriority">
     <code class="leafygreen-ui-1l06pbn">
      rangeDeleterHighPriority
     </code>
    </a>
    parameters. For example:
   </p>
   <ul class="leafygreen-ui-rioki0">
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      To limit the number of documents deleted per batch, you can set
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/parameters/#mongodb-parameter-param.rangeDeleterBatchSize">
       <code class="leafygreen-ui-1l06pbn">
        rangeDeleterBatchSize
       </code>
      </a>
      to a small value such as
      <code class="leafygreen-ui-1l06pbn">
       32
      </code>
      .
     </p>
    </li>
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      To add an additional delay between batch deletions, you can set
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/parameters/#mongodb-parameter-param.rangeDeleterBatchDelayMS">
       <code class="leafygreen-ui-1l06pbn">
        rangeDeleterBatchDelayMS
       </code>
      </a>
      above the current default of
      <code class="leafygreen-ui-1l06pbn">
       20
      </code>
      milliseconds.
     </p>
    </li>
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      To prioritize range deletions, you can set
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/parameters/#mongodb-parameter-param.rangeDeleterHighPriority">
       <code class="leafygreen-ui-1l06pbn">
        rangeDeleterHighPriority
       </code>
      </a>
      to
      <code class="leafygreen-ui-1l06pbn">
       true
      </code>
      . Range deletions
are potentially long-running background tasks that might negatively impact
the throughput of user operations when the system is under heavy load.
     </p>
    </li>
   </ul>
   <div class="leafygreen-ui-15mdk4" role="note">
    <h2 class="leafygreen-ui-6n7b7d">
     Note
    </h2>
    <div class="leafygreen-ui-9mycqc">
     <p class="leafygreen-ui-1kp3ins">
      If there are ongoing read operations or open cursors on the
collection targeted for deletes, range deletion processes may
not proceed.
     </p>
    </div>
   </div>
  </section>
  <section>
   <h3 class="contains-headerlink leafygreen-ui-15ajumo" weight="medium">
    Change Streams and Orphan Documents
    <a class="headerlink leafygreen-ui-1kepx47" href="#change-streams-and-orphan-documents" title="Permalink to this heading">
     <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
      <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
      </path>
      <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
      </path>
     </svg>
     <div class="css-1btu0w3 evvkmar0" id="change-streams-and-orphan-documents">
     </div>
    </a>
   </h3>
   <p class="leafygreen-ui-1kp3ins">
    Starting in MongoDB 5.3, during
    <a class="lg-ui-0001 leafygreen-ui-fgcsv5" href="#std-label-range-migration-procedure" target="_self">
     <span>
      range migration
     </span>
    </a>
    ,
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/changeStreams/#std-label-changeStreams">
     change stream
    </a>
    events are not generated for updates to
    <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/glossary/#std-term-orphaned-document">
     orphaned documents
     <!-- -->
     .
    </a>
   </p>
   <span class="leafygreen-ui-1qnjd6d" id="std-label-sharding-shard-size">
   </span>
  </section>
 </section>
 <section>
  <h2 class="contains-headerlink leafygreen-ui-19f71ei" weight="medium">
   Shard Size
   <a class="headerlink leafygreen-ui-1kepx47" href="#shard-size" title="Permalink to this heading">
    <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
     <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
     </path>
     <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
     </path>
    </svg>
    <div class="css-1btu0w3 evvkmar0" id="shard-size">
    </div>
   </a>
  </h2>
  <p class="leafygreen-ui-1kp3ins">
   By default, MongoDB attempts to fill all available disk space with
data on every shard as the data set grows. To ensure that the cluster
always has the capacity to handle data growth, monitor disk
usage as well as other performance metrics.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   See the
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-sharded-cluster-config-max-shard-size">
    Change the Maximum Storage Size for a Given Shard
   </a>
   tutorial for
instructions on setting the maximum size for a shard.
  </p>
 </section>
 <section>
  <h2 class="contains-headerlink leafygreen-ui-19f71ei" weight="medium">
   Chunk Size and Balancing
   <a class="headerlink leafygreen-ui-1kepx47" href="#chunk-size-and-balancing" title="Permalink to this heading">
    <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
     <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
     </path>
     <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
     </path>
    </svg>
    <div class="css-1btu0w3 evvkmar0" id="chunk-size-and-balancing">
    </div>
   </a>
  </h2>
  <p class="leafygreen-ui-1kp3ins">
   For an introduction to
   <code class="leafygreen-ui-1l06pbn">
    chunkSize
   </code>
   , see
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/modify-chunk-size-in-sharded-cluster/#std-label-tutorial-modifying-chunk-size">
    Modify Range Size in a Sharded Cluster
    <!-- -->
    .
   </a>
  </p>
  <p class="leafygreen-ui-1kp3ins">
   The following table describes how
   <code class="leafygreen-ui-1l06pbn">
    chunkSize
   </code>
   affects defragmentation
and the balancer operations in different MongoDB versions.
  </p>
  <div class="leafygreen-ui-skkc39" tabindex="0">
   <table class="leafygreen-ui-hr8lsv">
    <colgroup>
     <col style="width:30%"/>
     <col style="width:70%"/>
    </colgroup>
    <thead class="leafygreen-ui-a9ho40">
     <tr data-testid="leafygreen-ui-header-row">
      <th class="leafygreen-ui-1trtg6r" role="columnheader" scope="col">
       <div class="leafygreen-ui-ui0te9">
        <div>
         MongoDB Version
        </div>
       </div>
      </th>
      <th class="leafygreen-ui-13uteka" role="columnheader" scope="col">
       <div class="leafygreen-ui-ui0te9">
        <div>
         Description
        </div>
       </div>
      </th>
     </tr>
    </thead>
    <tbody>
     <tr class="">
      <td class="leafygreen-ui-1drjk7h">
       <div class="leafygreen-ui-1n4j8xf">
        <div>
         MongoDB 6.0 and later
        </div>
       </div>
      </td>
      <td class="leafygreen-ui-1drjk7h">
       <div class="leafygreen-ui-1n4j8xf">
        <div>
         <p class="leafygreen-ui-1kp3ins">
          When the collection data shared between two shards differs by
three or more times the configured
          <code class="leafygreen-ui-1l06pbn">
           chunkSize
          </code>
          setting, the
balancer migrates chunks between the shards.
         </p>
         <p class="leafygreen-ui-1kp3ins">
          For example, if
          <code class="leafygreen-ui-1l06pbn">
           chunkSize
          </code>
          is 128 MB and the collection data
differs by 384 MB or more, the balancer migrates chunks between
the shards.
         </p>
        </div>
       </div>
      </td>
     </tr>
     <tr class="">
      <td class="leafygreen-ui-1drjk7h">
       <div class="leafygreen-ui-1n4j8xf">
        <div>
         Earlier than MongoDB 6.0
        </div>
       </div>
      </td>
      <td class="leafygreen-ui-1drjk7h">
       <div class="leafygreen-ui-1n4j8xf">
        <div>
         When a chunk grows larger than
         <code class="leafygreen-ui-1l06pbn">
          chunkSize
         </code>
         , the chunk is split.
        </div>
       </div>
      </td>
     </tr>
    </tbody>
   </table>
  </div>
  <p class="leafygreen-ui-1kp3ins">
   When chunks are moved, split, or merged, the shard metadata is updated
after the chunk operation is committed by a
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/sharded-cluster-config-servers/#std-label-sharding-config-server">
    config server
   </a>
   . Shards not involved in the chunk operation
are also updated with new metadata.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   The time for the shard metadata update is proportional to the size of
the routing table. CRUD operations on the collection are temporarily
blocked while the shard metadata is updated, and a smaller routing table
means shorter CRUD operation delays.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   Defragmenting a collection reduces the number of chunks and the time to
update the chunk metadata.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   To reduce the system workload, configure the balancer to run only at a
specific time using a
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/tutorial/manage-sharded-cluster-balancer/#std-label-sharding-schedule-balancing-window">
    shard balancing window
   </a>
   . Defragmentation runs during the
balancing window time period.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   You can use the
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/parameters/#mongodb-parameter-param.chunkDefragmentationThrottlingMS">
    <code class="leafygreen-ui-1l06pbn">
     chunkDefragmentationThrottlingMS
    </code>
   </a>
   parameter
to limit the rate of split and merge commands run by the balancer.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   You can start and stop defragmentation at any time.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   You can also set a
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/zone-sharding/#std-label-zone-sharding">
    shard zone
   </a>
   . A shard zone is
based on the shard key, and you can associate each zone with one or more
shards in a cluster.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   Starting in MongoDB 6.0, a sharded cluster only splits chunks when
chunks must be migrated. This means the chunk size may exceed
   <code class="leafygreen-ui-1l06pbn">
    chunkSize
   </code>
   . Larger chunks reduce the number of chunks on a shard and
improve performance because the time to update the shard metadata is
reduced. For example, you might see a 1 TB chunk on a shard even though
you have set
   <code class="leafygreen-ui-1l06pbn">
    chunkSize
   </code>
   to 256 MB.
  </p>
  <p class="leafygreen-ui-1kp3ins">
   <code class="leafygreen-ui-1l06pbn">
    chunkSize
   </code>
   affects the following:
  </p>
  <ul class="leafygreen-ui-rioki0">
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     Maximum amount of data the balancer attempts to migrate between two
shards in a single chunk migration operation.
    </p>
   </li>
   <li class="leafygreen-ui-d7p7b6">
    <p class="leafygreen-ui-1kp3ins">
     Amount of data migrated during defragmentation.
    </p>
   </li>
  </ul>
  <p class="leafygreen-ui-1kp3ins">
   For details about defragmenting sharded collections, see
   <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/defragment-sharded-collections/#std-label-defragment-sharded-collections">
    Defragment Sharded Collections
    <!-- -->
    .
   </a>
  </p>
 </section>
</section>
