DOCS-15574 documents $toHashedIndexKey agg stage (#4701)

* DOCS-15574 documents toHashedIndexKey agg stage

* index page

* internal review

Author: jmd-mongo

source/includes/extracts-agg-operators.yaml

@@ -539,7 +539,6 @@ content: |
         - Description
 
       * - :expression:`$getField`
-
         - Returns the value of a specified field from a document. 
           You can use :expression:`$getField` to retrieve the value of 
           fields with names that contain periods (``.``) or start 
@@ -551,12 +550,16 @@ content: |
         - Returns a random float between 0 and 1
 
       * - :expression:`$sampleRate`
-
         - Randomly select documents at a given rate. Although the exact
           number of documents selected varies on each run, the quantity
           chosen approximates the sample rate expressed as a percentage
           of the total number of documents.
 
+      * - :expression:`$toHashedIndexKey`
+        - Computes and returns the hash of the input expression using 
+          the same hash function that MongoDB uses to create a hashed 
+          index.
+
 ---
 ref: agg-operators-objects
 content: |

source/reference/operator/aggregation.txt

@@ -1475,6 +1475,7 @@ Alphabetical Listing of Expression Operators
    /reference/operator/aggregation/toDate
    /reference/operator/aggregation/toDecimal
    /reference/operator/aggregation/toDouble
+   /reference/operator/aggregation/toHashedIndexKey
    /reference/operator/aggregation/toInt
    /reference/operator/aggregation/toLong
    /reference/operator/aggregation/toObjectId

source/reference/operator/aggregation/toHashedIndexKey.txt

@@ -0,0 +1,59 @@
+===============================
+$toHashedIndexKey (aggregation)
+===============================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. expression:: $toHashedIndexKey
+   
+   Computes and returns the hash value of the input expression using 
+   the same hash function that MongoDB uses to create a hashed index.
+   A hash function maps a key or string to a fixed-size numeric 
+   value.
+
+Syntax
+------
+
+``$toHashedIndexKey`` has the following syntax:
+
+.. code-block:: javascript
+
+   { $toHashedIndexKey: <key or string to hash> }
+
+Example
+-------
+
+You can use ``$toHashedIndexKey`` to compute the hashed value of a 
+string in an aggregation pipeline. This example computes the hashed
+value of the string ``"string to hash"``:
+
+.. code-block:: javascript
+   :emphasize-lines: 4
+
+   db.aggregate(
+      [ 
+         { $documents: [ { val: "string to hash" } ] },
+         { $addFields: { hashedVal: { $toHashedIndexKey: "$val" } } }
+      ]
+    )
+
+Example output:
+
+.. code-block:: javascript
+   :copyable: false
+
+   [ { val: 'string to hash', hashedVal: Long("763543691661428748") } ]
+
+Learn More
+----------
+
+- :method:`convertShardKeyToHashed()`