PYTHON-4940 - Add index hint as an explicit parameter for distinct command. (mongodb#2225)

Author: NoahStapp

doc/changelog.rst

@@ -9,6 +9,9 @@ PyMongo 4.12 brings a number of changes including:
 - Support for configuring DEK cache lifetime via the ``key_expiration_ms`` argument to
   :class:`~pymongo.encryption_options.AutoEncryptionOpts`.
 - Support for $lookup in CSFLE and QE supported on MongoDB 8.1+.
+- Added index hinting support to the
+  :meth:`~pymongo.asynchronous.collection.AsyncCollection.distinct` and
+  :meth:`~pymongo.collection.Collection.distinct` commands.
 
 Issues Resolved
 ...............

pymongo/asynchronous/collection.py

@@ -3111,6 +3111,7 @@ async def distinct(
         filter: Optional[Mapping[str, Any]] = None,
         session: Optional[AsyncClientSession] = None,
         comment: Optional[Any] = None,
+        hint: Optional[_IndexKeyHint] = None,
         **kwargs: Any,
     ) -> list:
         """Get a list of distinct values for `key` among all documents
@@ -3138,8 +3139,15 @@ async def distinct(
             :class:`~pymongo.asynchronous.client_session.AsyncClientSession`.
         :param comment: A user-provided comment to attach to this
             command.
+        :param hint: An index to use to support the query
+            predicate specified either by its string name, or in the same
+            format as passed to :meth:`~pymongo.asynchronous.collection.AsyncCollection.create_index`
+            (e.g. ``[('field', ASCENDING)]``).
         :param kwargs: See list of options above.
 
+        .. versionchanged:: 4.12
+           Added ``hint`` parameter.
+
         .. versionchanged:: 3.6
            Added ``session`` parameter.
 
@@ -3158,6 +3166,10 @@ async def distinct(
         cmd.update(kwargs)
         if comment is not None:
             cmd["comment"] = comment
+        if hint is not None:
+            if not isinstance(hint, str):
+                hint = helpers_shared._index_document(hint)
+            cmd["hint"] = hint  # type: ignore[assignment]
 
         async def _cmd(
             session: Optional[AsyncClientSession],

pymongo/synchronous/collection.py

@@ -3104,6 +3104,7 @@ def distinct(
         filter: Optional[Mapping[str, Any]] = None,
         session: Optional[ClientSession] = None,
         comment: Optional[Any] = None,
+        hint: Optional[_IndexKeyHint] = None,
         **kwargs: Any,
     ) -> list:
         """Get a list of distinct values for `key` among all documents
@@ -3131,8 +3132,15 @@ def distinct(
             :class:`~pymongo.client_session.ClientSession`.
         :param comment: A user-provided comment to attach to this
             command.
+        :param hint: An index to use to support the query
+            predicate specified either by its string name, or in the same
+            format as passed to :meth:`~pymongo.collection.Collection.create_index`
+            (e.g. ``[('field', ASCENDING)]``).
         :param kwargs: See list of options above.
 
+        .. versionchanged:: 4.12
+           Added ``hint`` parameter.
+
         .. versionchanged:: 3.6
            Added ``session`` parameter.
 
@@ -3151,6 +3159,10 @@ def distinct(
         cmd.update(kwargs)
         if comment is not None:
             cmd["comment"] = comment
+        if hint is not None:
+            if not isinstance(hint, str):
+                hint = helpers_shared._index_document(hint)
+            cmd["hint"] = hint  # type: ignore[assignment]
 
         def _cmd(
             session: Optional[ClientSession],