diff --git a/source/includes/apiargs-dbcommand-shardCollection-field.yaml b/source/includes/apiargs-dbcommand-shardCollection-field.yaml index 7f916dab384..112b4ab97f5 100644 --- a/source/includes/apiargs-dbcommand-shardCollection-field.yaml +++ b/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 `, + 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 ... diff --git a/source/includes/note-sharding-collation.rst b/source/includes/note-sharding-collation.rst new file mode 100644 index 00000000000..5ec01b760a7 --- /dev/null +++ b/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 `. \ No newline at end of file diff --git a/source/reference/command/shardCollection.txt b/source/reference/command/shardCollection.txt index 9bd8d054266..bb4b29d18ef 100644 --- a/source/reference/command/shardCollection.txt +++ b/source/reference/command/shardCollection.txt @@ -33,7 +33,8 @@ Definition shardCollection: ".", key: , unique: , - numInitialChunks: + numInitialChunks: , + 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 ` +Collation +~~~~~~~~~ + +.. versionchanged:: 3.4 + +If the collection has a default :doc:`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 ------- diff --git a/source/sharding.txt b/source/sharding.txt index f8056bfb07b..db2ba723d58 100644 --- a/source/sharding.txt +++ b/source/sharding.txt @@ -294,3 +294,21 @@ sharded clusters that span multiple data centers. See :ref:`zones ` 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 `. 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.