DOCS-11656: convertShardKeyToHashed.txt

Author: kay-kim

source/core/hashed-sharding.txt

@@ -7,9 +7,10 @@ Hashed Sharding
 
 .. default-domain:: mongodb
 
-Hashed sharding uses a :ref:`hashed index <index-hashed-index>` of a
-single field as the :term:`shard key` to partition data across your
-sharded cluster.
+Hashed sharding uses a :ref:`hashed index <index-hashed-index>` to
+partition data across your shared cluster. Hashed indexes compute the
+hash value of a single field as the index value; this value is used as
+your shard key. [#hashvalue]_
 
 .. include:: /images/sharding-hash-based.rst
 
@@ -29,6 +30,12 @@ collection using the :dbcommand:`split` command.
 
 .. include:: /includes/tip-applications-do-not-need-to-compute-hashes.rst
 
+.. [#hashvalue]
+   Starting in version 4.0, the :binary:`~bin.mongo` shell provides the
+   method :method:`convertShardKeyToHashed()`. This method uses the
+   same hashing function as the hashed index and can be used to see
+   what the hashed value would be for a key.
+
 .. _hashed-sharding-shard-key:
 
 Hashed Sharding Shard Key

source/core/index-hashed.txt

@@ -30,13 +30,19 @@ details.
 Hashing Function
 ----------------
 
-Hashed indexes use a hashing function to compute the
-hash of the value of the index field. The hashing function collapses
+Hashed indexes use a hashing function to compute the hash of the value
+of the index field. [#hashvalue]_ The hashing function collapses
 embedded documents and computes the hash for the entire value but does
 not support multi-key (i.e. arrays) indexes.
 
 .. include:: /includes/tip-applications-do-not-need-to-compute-hashes.rst
 
+.. [#hashvalue]
+   Starting in version 4.0, the :binary:`~bin.mongo` shell provides the
+   method :method:`convertShardKeyToHashed()`. This method uses the
+   same hashing function as the hashed index and can be used to see
+   what the hashed value would be for a key.
+
 Create a Hashed Index
 ---------------------
 

source/includes/ref-toc-method-sh.yaml

@@ -113,4 +113,8 @@ description: "Internal. Waits for a change in ping state from one of the :binary
 name: ":method:`sh.updateZoneKeyRange()`"
 file: /reference/method/sh.updateZoneKeyRange
 description: "Associates a range of shard keys to a zone. Supports configuring :ref:`zones <zone-sharding>` in sharded clusters."
+---
+name: ":method:`convertShardKeyToHashed.txt()`"
+file: /reference/method/convertShardKeyToHashed
+description: "Returns the hashed value for the input."
 ...

source/includes/warning-hashed-index-floating-point.rst

@@ -7,3 +7,6 @@
    point numbers that cannot be reliably converted to 64-bit
    integers (and then back to floating point). MongoDB ``hashed`` indexes do
    not support floating point values larger than 2\ :sup:`53`.
+
+   To see what the hashed value would be for a key, see
+   :method:`convertShardKeyToHashed()`.

source/reference/method/convertShardKeyToHashed.txt

@@ -0,0 +1,63 @@
+=======================
+convertShardKeyToHashed
+=======================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Description
+-----------
+
+.. method:: convertShardKeyToHashed(<document>)
+
+   Returns the hashed value for the input. The
+   :method:`convertShardKeyToHashed()` method uses the same hashing
+   function as the hashed index and can be used to see what the
+   :doc:`hashed value </core/hashed-sharding>` would be for a key.
+
+Example
+-------
+
+Consider a sharded collection that uses a :doc:`hashed shard key
+</core/hashed-sharding>` [#populated]_
+
+.. code-block:: javascript
+
+   use test
+
+   db.orders.createIndex( { _id: "hashed" } )
+
+   sh.shardCollection( "test.orders", { _id : "hashed" } )
+
+If the following document exists in the collection, the hashed value of
+the ``_id`` field is used to distribute the document:
+
+.. code-block:: javascript
+
+   {
+     _id: ObjectId("5b2be413c06d924ab26ff9ca"),
+     "item" : "Chocolates",
+     "qty" : 25
+   }
+   
+
+To determine the hashed value of ``_id`` field used to distribute the
+document across the shards, you can use the
+:method:`convertShardKeyToHashed` method:
+
+.. code-block:: javascrip
+
+   convertShardKeyToHashed( { _id: ObjectId("5b2be413c06d924ab26ff9ca") } )
+
+.. [#populated]
+
+   If the collection already contains data, you must create a hashed
+   index on the shard key before you shard the collection. For an empty
+   collection, MongoDB creates the index as part of
+   :method:`sh.shardCollection()`.
+

source/release-notes/4.0.txt

@@ -786,6 +786,10 @@ Miscellaneous
   :binary:`~bin.mongo` shell used the default ``MongoDB Shell`` value as the
   app name.
 
+- Adds a :binary:`~bin.mongo` shell method
+  :method:`convertShardKeyToHashed` to return the hashed value for a
+  document.
+
 Changes Affecting Compatibility
 -------------------------------
 

source/tutorial/deploy-sharded-cluster-hashed-sharding.txt

@@ -189,7 +189,7 @@ the :method:`sh.shardCollection()` method to shard a collection.
 If the collection already contains data, you must create a
 :ref:`index-type-hashed` on the :term:`shard key` using the
 :method:`db.collection.createIndex()` method before using
-:method:`~sh.shardCollection()`.
+:method:`~sh.shardCollection()`. [#hashvalue]_
 
 If the collection is empty, MongoDB creates the index as part of
 :method:`sh.shardCollection()`.
@@ -209,3 +209,9 @@ The following operation shards the target collection using the
   such as :ref:`zones <zone-sharding>`. See the selection
   considerations listed in the :ref:`hashed-sharding-shard-key`.
 
+.. [#hashvalue]
+   Starting in version 4.0, the :binary:`~bin.mongo` shell provides the
+   method :method:`convertShardKeyToHashed()`. This method uses the
+   same hashing function as the hashed index and can be used to see
+   what the hashed value would be for a key.
+