backport to v6.0 (#6277)

Author: jmd-mongo

source/administration/sharded-cluster-administration.txt

@@ -28,6 +28,7 @@ Sharded Cluster Administration
    /tutorial/backup-sharded-cluster-metadata
    /tutorial/convert-sharded-cluster-to-replica-set
    /tutorial/convert-replica-set-to-replicated-shard-cluster
+   /tutorial/drop-a-hashed-shard-key-index
 
 :doc:`Config Server Administration </administration/sharded-cluster-config-servers>`
    This section contains articles and tutorials related to sharded
@@ -67,3 +68,6 @@ Sharded Cluster Administration
    Convert a replica set to a sharded cluster in which each shard is
    its own replica set.
 
+:doc:`/tutorial/drop-a-hashed-shard-key-index`
+   Drop a Hashed Shard Key Index.
+

source/core/hashed-sharding.txt

@@ -249,6 +249,10 @@ Sharding Empty Collection on Compound Hashed Shard Key with Non-Hashed Prefix
      :ref:`pre-define-zone-range-hashed-example`.
 
 
+Drop a Hashed Shard Key Index 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/drop-hashed-shard-key-index.rst
 
 
 .. seealso::

source/includes/drop-hashed-shard-key-index-main.rst

@@ -0,0 +1,6 @@
+Starting in MongoDB 7.0.3 (and 6.0.12 and 5.0.22), you can drop the 
+index for a hashed shard key.
+
+This can speed up data insertion for collections sharded with a hashed 
+shard key. It can also speed up data ingestion when using 
+``mongosync``.

source/includes/drop-hashed-shard-key-index.rst

@@ -0,0 +1,3 @@
+.. include:: /includes/drop-hashed-shard-key-index-main.rst
+
+For details, see :ref:`drop-a-hashed-shard-key-index`.

source/includes/shardedDataDistribution-output-example.rst

@@ -0,0 +1,24 @@
+.. code-block:: json
+
+   [
+     {
+       "ns": "test.names",
+       "shards": [
+         {
+           "shardName": "shard-1",
+           "numOrphanedDocs": 0,
+           "numOwnedDocuments": 6,
+           "ownedSizeBytes": 366,
+           "orphanedSizeBytes": 0
+         },
+         {
+           "shardName": "shard-2",
+           "numOrphanedDocs": 0,
+           "numOwnedDocuments": 6,
+           "ownedSizeBytes": 366,
+           "orphanedSizeBytes": 0
+         }
+       ]
+     }
+   ]
+

source/reference/operator/aggregation/shardedDataDistribution.txt

@@ -59,27 +59,4 @@ Examples
 
 Example output:
 
-.. code-block:: json
-
-   [
-     {
-       "ns": "test.names",
-       "shards": [
-         {
-           "shardName": "shard-1",
-           "numOrphanedDocs": 0,
-           "numOwnedDocuments": 6,
-           "ownedSizeBytes": 366,
-           "orphanedSizeBytes": 0
-         },
-         {
-           "shardName": "shard-2",
-           "numOrphanedDocs": 0,
-           "numOwnedDocuments": 6,
-           "ownedSizeBytes": 366,
-           "orphanedSizeBytes": 0
-         }
-       ]
-     }
-   ]
-
+.. include:: /includes/shardedDataDistribution-output-example.rst

source/release-notes/6.0.txt

@@ -1001,6 +1001,11 @@ performance. For more information and an example, see
 General Improvements
 --------------------
 
+Drop a Hashed Shard Key Index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/drop-hashed-shard-key-index.rst
+
 OpenSSL3 FIPS Support
 ~~~~~~~~~~~~~~~~~~~~~
 

source/tutorial/drop-a-hashed-shard-key-index.txt

@@ -0,0 +1,93 @@
+.. _drop-a-hashed-shard-key-index:
+
+=============================
+Drop a Hashed Shard Key Index
+=============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. include:: /includes/drop-hashed-shard-key-index-main.rst
+
+About this Task
+---------------
+
+Dropping an `unnecessary index 
+<http://www.mongodb.com/developer/products/mongodb/schema-design-anti-pattern-unnecessary-indexes/>`_ 
+can speed up CRUD operations. Each CRUD operation has to update all the 
+indexes related to a document. Removing one index can increase the 
+speed of all CRUD operations.  
+
+When you drop a hashed shard key index, the server disables balancing 
+for that collection and excludes the collection from future balancing
+rounds. In order to include the collection in balancing rounds once
+again, you must recreate the shard key index. 
+
+Steps
+-----
+
+.. procedure::
+   :style: normal
+
+   .. step:: Stop the balancer
+  
+      Run the following command to stop the balancer:
+
+      .. code-block:: javascript
+
+         sh.stopBalancer()
+
+      You can only run ``sh.stopBalancer()`` on ``mongos``. 
+      ``sh.stopBalancer()`` produces an error if run on ``mongod``.
+
+   .. step:: Confirm there are no orphaned documents in your collection
+
+      Starting in MongoDB 6.0.3, you can run an aggregation using the 
+      :pipeline:`$shardedDataDistribution` stage to confirm no orphaned 
+      documents remain:
+
+      .. code-block:: javascript
+
+         db.aggregate([ 
+            { $shardedDataDistribution: {} },
+            { $match: { "ns": "<database>.<collection>" } }
+         ])
+
+      ``$shardedDataDistribution`` has output similar to the following:
+
+      .. include:: /includes/shardedDataDistribution-output-example.rst
+
+      Ensure that ``"numOrphanedDocs"`` is ``0`` for each shard in the
+      cluster.
+
+   .. step:: Drop the hashed shard key index 
+
+      Run the following command to drop the index:
+ 
+      .. code-block:: javascript
+
+         db.collection.dropIndex("<index name>")
+
+   .. step:: Restart the balancer
+
+      Run the following command to restart the balancer on the cluster:
+
+      .. code-block:: javascript
+
+         sh.startBalancer()
+
+
+Learn More
+----------
+
+- :ref:`sharding-hashed`
+- :ref:`sharding-balancing`
+- :method:`db.collection.dropIndex()`
+- :method:`sh.stopBalancer()`
+- :method:`sh.startBalancer()`
+- :method:`sh.getBalancerState()`