DOCSP-50584 reShard Collection to Shard (#12452)

Author: kennethdyer

content/manual/upcoming/source/core/reshard-to-same-key.txt

@@ -76,6 +76,8 @@ Latency
 
 .. include:: /includes/reshard-to-same-key/latency.rst
 
+.. _reshard-to-same-key-req:
+
 Additional Resource Requirements
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

content/manual/upcoming/source/includes/fact-reshard-init-shard.rst

@@ -0,0 +1,27 @@
+
+When you run the |shardCmd|, the balancer begins distributing
+the collection data to other shards in the cluster. A single
+shard can only participate in one chunk migration at a time,
+When MongoDB succeeds in copying a range of data from one shard
+to another, the range on the donor shard is marked for removal
+by the range deleter. This process is slow and resource
+intensive.
+
+Starting in MongoDB 8.0, if your deployment meets the
+:ref:`resource requirements <reshard-to-same-key-req>`, it's
+recommended you use the |reshardCmd| to perform this initial
+balancing of data by resharding to the same key. This causes
+MongoDB to rebalance data across the shards without waiting on
+the balancer.
+
+To use the |reshardCmd| to perform the initial balancing:
+
+#. Use the |shardCmd| to configure the collection as a sharded
+   collection. 
+
+#. Use the |reshardCmd| to reshard to the same shard key by
+   setting the ``forceRedistribution`` option to ``true``.
+   MongoDB then balances the data across the shards.
+
+For more information, see :ref:`reshard-to-same-key`.
+

content/manual/upcoming/source/reference/command/shardCollection.txt

@@ -237,6 +237,14 @@ Use the form ``field: "hashed"`` to specify a hashed shard key field.
 
    :doc:`/core/hashed-sharding`
 
+Reshard to Balance
+~~~~~~~~~~~~~~~~~~
+
+.. |shardCmd| replace:: :dbcommand:`shardCollection` command
+.. |reshardCmd| replace:: :dbcommand:`reshardCollection` command
+
+.. include:: /includes/fact-reshard-init-shard
+
 .. _shardCollection-zones:
 
 Zone Sharding and Initial Chunk Distribution
@@ -298,4 +306,4 @@ Learn More
 - :method:`sh.balancerCollectionStatus()`
 - :method:`sh.shardCollection()`
 - :doc:`/sharding`
-- :ref:`reshard-to-same-key`
+- :ref:`reshard-to-same-key`

content/manual/upcoming/source/reference/method/sh.shardCollection.txt

@@ -288,6 +288,14 @@ Write Concern
 
 .. include:: /includes/extracts/mongos-operations-wc-shard-collection.rst
 
+Reshard to Balance
+~~~~~~~~~~~~~~~~~~
+
+.. |shardCmd| replace:: :method:`sh.shardCollection` method
+.. |reshardCmd| replace:: :method:`sh.reshardCollection` method
+
+.. include:: /includes/fact-reshard-init-shard
+
 Examples
 --------
 
@@ -332,4 +340,4 @@ following example uses
    - :dbcommand:`refineCollectionShardKey`
    - :method:`sh.balancerCollectionStatus()`
    - :dbcommand:`shardCollection`
-   - :doc:`/sharding`
+   - :doc:`/sharding`