DOCSP-29669 resharding improvements (#5120) (#5544)

* DOCSP-29669 reshard improvements

* Fixes per Ashley

* Empty change to force rebuild

* Empty change to force rebuild

* Fixes per Ashley



* Fixes per Ashley

* Fixes spacing

* Fixes per Ashley



* Fixes per Matt

* Fixes per Matt

* Fixes per Matt

* Fixes per Matt

* Removes stray duplicate interlink

* Fixes per Matt

* Fixes per Matt

* Fixes per Matt

* Fixes per Matt

* Fixes per Matt

* Fixes per Ratika

* Fixes per Ratika

* Fixes per Matt

---------

Co-authored-by: Ashley Brown <[email protected]>

Author: kennethdyer

source/core/sharding-balancer-administration.txt

@@ -97,6 +97,15 @@ shard immediately, it can take some time before the cluster balances.
 See the :ref:`Add Shards to a Cluster <sharding-procedure-add-shard>` 
 tutorial for instructions on adding a shard to a cluster.
 
+.. tip::
+
+   If your application meets the :ref:`reshard-requirements`, you can use the
+   :dbcommand:`reshardCollection` command to redistribute data across the
+   cluster to include the new shards.  This process is much faster than the
+   alternative :ref:`range-migration-procedure`.
+
+   For an example, see :ref:`reshardCollection-redistribute-data`.
+
 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 

source/core/sharding-reshard-a-collection.txt

@@ -17,9 +17,14 @@ Reshard a Collection
 The ideal shard key allows MongoDB to distribute documents evenly
 throughout the cluster while facilitating common query patterns. A
 suboptimal shard key can lead to performance or scaling issues due to
-uneven data distribution. Starting in MongoDB 5.0, you can change the
-shard key for a collection to change the distribution of your data
-across a cluster.
+uneven data distribution. 
+
+Starting in MongoDB 5.0, you can change the shard key for a collection to
+change the distribution of your data across a cluster.
+
+Starting in MongoDB 7.2, you can reshard a collection on the same shard key,
+allowing you to redistribute data to include new shards or to different zones
+without changing your shard key.
 
 .. note::
 

source/reference/command/reshardCollection.txt

@@ -31,7 +31,7 @@ The command has the following syntax:
 
 .. code-block:: javascript
 
-   db.runCommand(
+   db.adminCommand(
       {
         reshardCollection: "<database>.<collection>",
         key: <shardkey>,
@@ -45,7 +45,8 @@ The command has the following syntax:
                 zone: <string> | null
             },
             ...
-        ]
+        ],
+        forceDistribution: <bool>
       }
    )
 
@@ -109,9 +110,15 @@ The command takes the following fields:
      - array
      - Optional. To maintain or add :ref:`zones <zone-sharding>`,
        specify the zones for your collection in an array.
- 
-The :binary:`~bin.mongosh` provides a wrapper method
-:method:`sh.reshardCollection()`.
+
+   * - ``forceRedistribution``
+     - boolean
+     - Optional.  When set to ``true``, the operation executes even if the new
+       shard key is the same as the old shard key.  Use with the 
+       ``zones`` option to move data to specific zones.
+
+       .. versionadded:: 7.2
+
 
 Resharding Process
 ------------------
@@ -217,3 +224,54 @@ MongoDB returns the following:
 .. seealso::
 
    :ref:`sharding-resharding`
+
+.. _reshardCollection-redistribute-data:
+
+Redistribute Data to New Shards
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 7.2, you can reshard a collection on the same key,
+which can be used to redistribute data onto new shards.
+
+After adding a shard to the cluster, you use the ``reshardCollection`` command
+with the ``forceRedistribution`` option to redistribute data across the
+cluster:
+
+.. code-block:: javascript
+
+   db.adminCommand({
+       reshardCollection: "accounts.invoices",
+       key: { store_id: "hashed" },
+       forceRedistribution: true
+   })
+
+
+Redistribute Data to Different Zones
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Starting in MongoDB 7.2, you can use the ``reshardCollection`` command to
+move data into new zones without changing the shard key.
+
+The following command redistributes data for the ``accounts.sales`` collection
+using the same shard key, moving data from zones ``zone01`` and ``zone02`` to
+``zone03`` and ``zone04``:
+
+.. code-block:: javascript
+   
+   db.adminCommand({
+       reshardCollection: "accounts.sales",
+       key: { region_id: "hashed" },
+       forceRedistribution: true,
+       zones: [
+           {
+               zone: "zone04",
+               min: { region_id: MinKey() },
+               max: { region_id: 10 }
+           },
+           {
+               zone: "zone05",
+               min: { region_id: 10 },
+               max: { region_id: MaxKey() }
+           }
+       ]
+   })

source/release-notes/7.2.txt

@@ -58,8 +58,37 @@ Starting in MongoDB 7.2, when you :ref:`shard an empty collection
 creates one chunk per shard by default. Previously, the operation
 created two chunks by default.
 
+Resharding Improvements
+-----------------------
+
+MongoDB 7.2 introduces significant performance improvements in reshard
+collection operations, substantially reducing the amount of time the 
+operation takes to run.
+
+Additionally, if your application and cluster meet the necessary
+:ref:`requirements <reshard-requirements>` and :ref:`limitations
+<resharding-limitations>`, you can reshard the collection on the same key using
+the :dbcommand:`reshardCollection` command to redistribute your collection,
+which is much faster than alternative :ref:`range migration procedure
+<range-migration-procedure>`.
+
+The following options are added to the command:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Field
+     - Description
+
+   * - ``forceRedistribution``
+     - Enables same-key resharding.
+
+For examples, see :ref:`reshardCollection-redistribute-data`.
+
 .. toctree::
    :titlesonly:
    :hidden:
 
    /release-notes/7.2-compatibility
+
+