diff --git a/source/includes/apiargs-dbcommand-shardCollection-field.yaml b/source/includes/apiargs-dbcommand-shardCollection-field.yaml index 112b4ab97f5..8df9de332a6 100644 --- a/source/includes/apiargs-dbcommand-shardCollection-field.yaml +++ b/source/includes/apiargs-dbcommand-shardCollection-field.yaml @@ -32,7 +32,7 @@ arg_name: field description: | When ``true``, the ``unique`` option ensures that the underlying index enforces a unique constraint. Hashed shard keys do not support unique - constraints. + constraints. Defaults to ``false``. interface: dbcommand name: unique @@ -60,7 +60,8 @@ arg_name: field description: | If the collection specified to ``shardCollection`` has a default :doc:`collation `, - you *must* set {{role}} to ``{ locale : "simple"}``, or + you *must* include a collation document with + ``{ 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. diff --git a/source/includes/apiargs-method-sh.shardCollection-options-param.yaml b/source/includes/apiargs-method-sh.shardCollection-options-param.yaml new file mode 100644 index 00000000000..57d9b694a6b --- /dev/null +++ b/source/includes/apiargs-method-sh.shardCollection-options-param.yaml @@ -0,0 +1,23 @@ +arg_name: param +source: + file: apiargs-dbcommand-shardCollection-field.yaml + ref: numInitialChunks + +interface: method +name: numInitialChunks +operation: sh.shardCollection +optional: true +position: 1 +type: integer +--- +arg_name: param +source: + file: apiargs-dbcommand-shardCollection-field.yaml + ref: collation +interface: method +name: collation +operation: sh.shardCollection +optional: true +position: 2 +type: document +... \ No newline at end of file diff --git a/source/includes/apiargs-method-sh.shardCollection-param.yaml b/source/includes/apiargs-method-sh.shardCollection-param.yaml index 3f861b41a36..ab35679cdf4 100644 --- a/source/includes/apiargs-method-sh.shardCollection-param.yaml +++ b/source/includes/apiargs-method-sh.shardCollection-param.yaml @@ -28,7 +28,18 @@ source: interface: method name: unique operation: sh.shardCollection -optional: false +optional: true position: 3 type: boolean +--- +arg_name: param +description: | + A document containing optional fields, including + ``numInitialChunks`` and ``collation``. +interface: method +name: options +operation: sh.shardCollection +optional: true +position: 4 +type: document ... diff --git a/source/includes/extracts-collation.yaml b/source/includes/extracts-collation.yaml index 9b0f8fde7fc..7c97642edd4 100644 --- a/source/includes/extracts-collation.yaml +++ b/source/includes/extracts-collation.yaml @@ -166,6 +166,10 @@ content: |- | :method:`db.collection.updateMany()`, | :method:`db.collection.replaceOne()` + * - :dbcommand:`shardCollection` + + - | :method:`sh.shardCollection()` + * - - Individual update, replace, and delete operations in diff --git a/source/includes/fact-shardCollection-collation.rst b/source/includes/fact-shardCollection-collation.rst new file mode 100644 index 00000000000..427420911f5 --- /dev/null +++ b/source/includes/fact-shardCollection-collation.rst @@ -0,0 +1,14 @@ +Collation +~~~~~~~~~ + +.. versionchanged:: 3.4 + +If the collection has a default :doc:`collation`, +the |command| command must include a ``collation`` parameter with the +value ``{ locale: "simple" }``. For non-empty collections with a +default 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. \ No newline at end of file diff --git a/source/reference/command/shardCollection.txt b/source/reference/command/shardCollection.txt index bb4b29d18ef..15d07673b5e 100644 --- a/source/reference/command/shardCollection.txt +++ b/source/reference/command/shardCollection.txt @@ -84,21 +84,7 @@ 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. +.. include:: /includes/fact-shardCollection-collation.rst Example ------- diff --git a/source/reference/method/sh.shardCollection.txt b/source/reference/method/sh.shardCollection.txt index 1fae4226937..a39a82df229 100644 --- a/source/reference/method/sh.shardCollection.txt +++ b/source/reference/method/sh.shardCollection.txt @@ -13,13 +13,19 @@ sh.shardCollection() Definition ---------- -.. method:: sh.shardCollection(namespace, key, unique) +.. method:: sh.shardCollection(namespace, key, unique, options) + + .. |command| replace:: :method:`sh.shardCollection` Shards a collection using the ``key`` as a the :term:`shard key`. :method:`sh.shardCollection()` takes the following arguments: .. include:: /includes/apiargs/method-sh.shardCollection-param.rst +The ``options`` argument supports the following options: + +.. include:: /includes/apiargs/method-sh.shardCollection-options-param.rst + Considerations -------------- @@ -54,16 +60,38 @@ If specifying ``unique: true``: See also :ref:`Sharded Collection and Unique Indexes ` + +.. include:: /includes/fact-shardCollection-collation.rst -Example -------- +Examples +-------- + +Simple Usage +~~~~~~~~~~~~ -Given the ``people`` collection in the ``records`` database, the -following command shards the collection by the ``zipcode`` field: +Given a collection named ``people`` in a database named ``records``, +the following command shards the collection by the +``zipcode`` field: .. code-block:: javascript - sh.shardCollection("records.people", { zipcode: 1} ) + sh.shardCollection("records.people", { zipcode: 1 } ) -.. seealso:: :dbcommand:`shardCollection`, :doc:`/sharding` +Usage with Options +~~~~~~~~~~~~~~~~~~ +Given a collection named ``contacts`` in a database named ``phonebook``, +the following command: + +- Shards the collection by the ``last_name`` field. +- Indicates that there is no unique constraint on the underlying + index. +- Specifies ``5`` initial chunks. +- Specifies a :doc:`collation`. + +.. code-block:: javascript + + sh.shardCollection("phonebook.contacts", { last_name: 1 }, false, + { numInitialChunks: 5, collation: { locale: "simple" } } ) + +.. seealso:: :dbcommand:`shardCollection`, :doc:`/sharding`