DOCS-8851: update shardCollection command for collation

source/includes/apiargs-dbcommand-shardCollection-field.yaml

@@ -55,4 +55,19 @@ operation: shardCollection
 optional: false
 position: 4
 type: integer
+---
+arg_name: field
+description: |
+  If the collection specified to ``shardCollection``
+  has a default :doc:`collation </reference/collation>`,
+  you *must* set {{role}} to ``{ locale : "simple"}``, or
+  the ``shardCollection`` command fails. At least one of the indexes
+  whose fields support the shard key pattern must have the simple
+  collation.
+interface: dbcommand
+name: collation
+operation: shardCollection
+optional: true
+position: 5
+type: document
 ...

source/includes/note-sharding-collation.rst

@@ -0,0 +1,6 @@
+.. note::
+
+   Queries on the sharded collection continue to use the default
+   collation configured for the collection. To use the shard key
+   index's ``simple`` collation, specify ``{locale : "simple"}``
+   in the query's :doc:`collation document </reference/collation>`.

source/reference/command/shardCollection.txt

@@ -33,7 +33,8 @@ Definition
          shardCollection: "<database>.<collection>",
          key: <shardkey>,
          unique: <boolean>,
-         numInitialChunks: <integer>
+         numInitialChunks: <integer>,
+         collation: { locale: "simple" }
       }
 
    :dbcommand:`shardCollection` has the following fields:
@@ -83,6 +84,22 @@ If specifying ``unique: true``:
 See also :ref:`Sharded Collection and Unique Indexes
 <sharding-shard-key-unique>`
 
+Collation
+~~~~~~~~~
+
+.. versionchanged:: 3.4
+
+If the collection has a default :doc:`collation</reference/collation>`,
+your :dbcommand:`shardCollection` command must include a
+``collation`` parameter with the value ``{ locale: "simple" }``.
+For non-empty collections with a collation, you must have at
+least one index with the simple collation whose fields support the
+shard key pattern.
+
+You do not need to specify the ``collation`` option for collections
+without a collation. If you do specify the collation option for
+a collection with no collation, it will have no effect.
+
 Example
 -------
 

source/sharding.txt

@@ -294,3 +294,21 @@ sharded clusters that span multiple data centers.
 
 See :ref:`zones <zone-sharding>` for more information.
 
+Collations in Sharding
+----------------------
+
+Use the :dbcommand:`shardCollection` command with the ``collation :
+{ locale : "simple" }`` option to shard a collection which has a
+:doc:`default collation </reference/collation>`. Successful 
+sharding requires that:
+
+- The collection must have an index whose prefix is the shard key
+- The index must have the collation ``{ locale: "simple" }``
+
+When creating new collections with a collation, ensure these conditions
+are met prior to sharding the collection.
+
+.. include:: /includes/note-sharding-collation.rst
+
+See :dbcommand:`shardCollection` for more information about sharding
+and collation.