From 77b1f78458cf25b525cde2274e33acd5db2581d2 Mon Sep 17 00:00:00 2001
From: Matt Dale <9760375+matthewdale@users.noreply.github.com>
Date: Mon, 4 Nov 2024 08:21:13 -0800
Subject: [PATCH] DRIVERS-2658 Add hint support for distinct. (#1715)

---
 source/crud/crud.md                          |  12 ++
 source/crud/tests/unified/distinct-hint.json | 139 +++++++++++++++++++
 source/crud/tests/unified/distinct-hint.yml  |  73 ++++++++++
 3 files changed, 224 insertions(+)
 create mode 100644 source/crud/tests/unified/distinct-hint.json
 create mode 100644 source/crud/tests/unified/distinct-hint.yml

diff --git a/source/crud/crud.md b/source/crud/crud.md
index 2b1fb19b88..9e7ce82e6c 100644
--- a/source/crud/crud.md
+++ b/source/crud/crud.md
@@ -427,6 +427,16 @@ class DistinctOptions {
    * and providing one will result in a server-side error.
    */
   comment: Optional<any>;
+
+  /**
+   * The index to use. Specify either the index name as a string or the index key pattern.
+   * If specified, then the query system will only consider plans using the hinted index.
+   *
+   * This option is sent only if the caller explicitly provides a value. The default is to not send a value.
+   *
+   * @see https://www.mongodb.com/docs/manual/reference/command/find/
+   */
+  hint: Optional<(String | Document)>;
 }
 
 enum CursorType {
@@ -2488,6 +2498,8 @@ aforementioned allowance in the SemVer spec.
 
 - 2024-11-04: Always send a value for `bypassDocumentValidation` if it was specified.
 
+- 2024-11-01: Add hint to DistinctOptions
+
 - 2024-10-30: Document query limitations in `countDocuments`.
 
 - 2024-10-28: Clarified that generated identifiers should be prepended to documents.
diff --git a/source/crud/tests/unified/distinct-hint.json b/source/crud/tests/unified/distinct-hint.json
new file mode 100644
index 0000000000..2a6869cbe0
--- /dev/null
+++ b/source/crud/tests/unified/distinct-hint.json
@@ -0,0 +1,139 @@
+{
+  "description": "distinct-hint",
+  "schemaVersion": "1.0",
+  "runOnRequirements": [
+    {
+      "minServerVersion": "7.1.0"
+    }
+  ],
+  "createEntities": [
+    {
+      "client": {
+        "id": "client0",
+        "observeEvents": [
+          "commandStartedEvent"
+        ]
+      }
+    },
+    {
+      "database": {
+        "id": "database0",
+        "client": "client0",
+        "databaseName": "distinct-hint-tests"
+      }
+    },
+    {
+      "collection": {
+        "id": "collection0",
+        "database": "database0",
+        "collectionName": "coll0"
+      }
+    }
+  ],
+  "initialData": [
+    {
+      "collectionName": "coll0",
+      "databaseName": "distinct-hint-tests",
+      "documents": [
+        {
+          "_id": 1,
+          "x": 11
+        },
+        {
+          "_id": 2,
+          "x": 22
+        },
+        {
+          "_id": 3,
+          "x": 33
+        }
+      ]
+    }
+  ],
+  "tests": [
+    {
+      "description": "distinct with hint string",
+      "operations": [
+        {
+          "name": "distinct",
+          "object": "collection0",
+          "arguments": {
+            "fieldName": "x",
+            "filter": {
+              "_id": 1
+            },
+            "hint": "_id_"
+          },
+          "expectResult": [
+            11
+          ]
+        }
+      ],
+      "expectEvents": [
+        {
+          "client": "client0",
+          "events": [
+            {
+              "commandStartedEvent": {
+                "command": {
+                  "distinct": "coll0",
+                  "key": "x",
+                  "query": {
+                    "_id": 1
+                  },
+                  "hint": "_id_"
+                },
+                "commandName": "distinct",
+                "databaseName": "distinct-hint-tests"
+              }
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "description": "distinct with hint document",
+      "operations": [
+        {
+          "name": "distinct",
+          "object": "collection0",
+          "arguments": {
+            "fieldName": "x",
+            "filter": {
+              "_id": 1
+            },
+            "hint": {
+              "_id": 1
+            }
+          },
+          "expectResult": [
+            11
+          ]
+        }
+      ],
+      "expectEvents": [
+        {
+          "client": "client0",
+          "events": [
+            {
+              "commandStartedEvent": {
+                "command": {
+                  "distinct": "coll0",
+                  "key": "x",
+                  "query": {
+                    "_id": 1
+                  },
+                  "hint": {
+                    "_id": 1
+                  }
+                },
+                "commandName": "distinct",
+                "databaseName": "distinct-hint-tests"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
diff --git a/source/crud/tests/unified/distinct-hint.yml b/source/crud/tests/unified/distinct-hint.yml
new file mode 100644
index 0000000000..9d277616d3
--- /dev/null
+++ b/source/crud/tests/unified/distinct-hint.yml
@@ -0,0 +1,73 @@
+description: "distinct-hint"
+
+schemaVersion: "1.0"
+runOnRequirements:
+  # https://jira.mongodb.org/browse/SERVER-14227
+  # Server supports distinct with hint starting from 7.1.0.
+  - minServerVersion: "7.1.0"
+
+createEntities:
+  - client:
+      id: &client0 client0
+      observeEvents: [ commandStartedEvent ]
+  - database:
+      id: &database0 database0
+      client: *client0
+      databaseName: &database0Name distinct-hint-tests
+  - collection:
+      id: &collection0 collection0
+      database: *database0
+      collectionName: &collection0Name coll0
+
+initialData:
+  - collectionName: *collection0Name
+    databaseName: *database0Name
+    documents:
+      - { _id: 1, x: 11 }
+      - { _id: 2, x: 22 }
+      - { _id: 3, x: 33 }
+
+tests:
+  - description: "distinct with hint string"
+    operations:
+      - name: distinct
+        object: *collection0
+        arguments:
+          fieldName: &fieldName x
+          filter: &filter { _id: 1 }
+          hint: _id_
+        expectResult: [ 11 ]
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                distinct: *collection0Name
+                key: *fieldName
+                query: *filter
+                hint: _id_
+              commandName: distinct
+              databaseName: *database0Name
+
+  - description: "distinct with hint document"
+    operations:
+      - name: distinct
+        object: *collection0
+        arguments:
+          fieldName: *fieldName
+          filter: *filter
+          hint:
+            _id: 1
+        expectResult: [ 11 ]
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                distinct: *collection0Name
+                key: *fieldName
+                query: *filter
+                hint:
+                  _id: 1
+              commandName: distinct
+              databaseName: *database0Name