PYTHON-2142 Add index hinting support to delete operations

Author: prashantmital

pymongo/bulk.py

@@ -218,14 +218,17 @@ def add_replace(self, selector, replacement, upsert=False,
             cmd['hint'] = hint
         self.ops.append((_UPDATE, cmd))
 
-    def add_delete(self, selector, limit, collation=None):
+    def add_delete(self, selector, limit, collation=None, hint=None):
         """Create a delete document and add it to the list of ops.
         """
         cmd = SON([('q', selector), ('limit', limit)])
         collation = validate_collation_or_none(collation)
         if collation is not None:
             self.uses_collation = True
             cmd['collation'] = collation
+        if hint is not None:
+            self.uses_hint = True
+            cmd['hint'] = hint
         if limit == _DELETE_ALL:
             # A bulk_write containing a delete_many is not retryable.
             self.is_retryable = False

pymongo/collection.py

@@ -1125,7 +1125,7 @@ def drop(self, session=None):
     def _delete(
             self, sock_info, criteria, multi,
             write_concern=None, op_id=None, ordered=True,
-            collation=None, session=None, retryable_write=False):
+            collation=None, hint=None, session=None, retryable_write=False):
         """Internal delete helper."""
         common.validate_is_mapping("filter", criteria)
         write_concern = write_concern or self.write_concern
@@ -1142,6 +1142,16 @@ def _delete(
                     'Collation is unsupported for unacknowledged writes.')
             else:
                 delete_doc['collation'] = collation
+        if hint is not None:
+            if sock_info.max_wire_version < 5:
+                raise ConfigurationError(
+                    'Must be connected to MongoDB 3.4+ to use hint.')
+            elif not acknowledged:
+                raise ConfigurationError(
+                    'hint is unsupported for unacknowledged writes.')
+            if not isinstance(hint, string_type):
+                hint = helpers._index_document(hint)
+            delete_doc['hint'] = hint
         command = SON([('delete', self.name),
                        ('ordered', ordered),
                        ('deletes', [delete_doc])])
@@ -1171,20 +1181,20 @@ def _delete(
     def _delete_retryable(
             self, criteria, multi,
             write_concern=None, op_id=None, ordered=True,
-            collation=None, session=None):
+            collation=None, hint=None, session=None):
         """Internal delete helper."""
         def _delete(session, sock_info, retryable_write):
             return self._delete(
                 sock_info, criteria, multi,
                 write_concern=write_concern, op_id=op_id, ordered=ordered,
-                collation=collation, session=session,
+                collation=collation, hint=hint, session=session,
                 retryable_write=retryable_write)
 
         return self.__database.client._retryable_write(
             (write_concern or self.write_concern).acknowledged and not multi,
             _delete, session)
 
-    def delete_one(self, filter, collation=None, session=None):
+    def delete_one(self, filter, collation=None, hint=None, session=None):
         """Delete a single document matching the filter.
 
           >>> db.test.count_documents({'x': 1})
@@ -1200,29 +1210,35 @@ def delete_one(self, filter, collation=None, session=None):
           - `collation` (optional): An instance of
             :class:`~pymongo.collation.Collation`. This option is only supported
             on MongoDB 3.4 and above.
+          - `hint` (optional): 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)]``). This option is only supported on
+            MongoDB 4.4 and above.
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
 
         :Returns:
           - An instance of :class:`~pymongo.results.DeleteResult`.
 
+        .. versionchanged:: 3.11
+           Added ``hint`` parameter.
         .. versionchanged:: 3.6
            Added ``session`` parameter.
-
         .. versionchanged:: 3.4
           Added the `collation` option.
-
         .. versionadded:: 3.0
         """
         write_concern = self._write_concern_for(session)
         return DeleteResult(
             self._delete_retryable(
                 filter, False,
                 write_concern=write_concern,
-                collation=collation, session=session),
+                collation=collation, hint=hint, session=session),
             write_concern.acknowledged)
 
-    def delete_many(self, filter, collation=None, session=None):
+    def delete_many(self, filter, collation=None, hint=None, session=None):
         """Delete one or more documents matching the filter.
 
           >>> db.test.count_documents({'x': 1})
@@ -1238,26 +1254,32 @@ def delete_many(self, filter, collation=None, session=None):
           - `collation` (optional): An instance of
             :class:`~pymongo.collation.Collation`. This option is only supported
             on MongoDB 3.4 and above.
+          - `hint` (optional): 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)]``). This option is only supported on
+            MongoDB 4.4 and above.
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
 
         :Returns:
           - An instance of :class:`~pymongo.results.DeleteResult`.
 
+        .. versionchanged:: 3.11
+           Added ``hint`` parameter.
         .. versionchanged:: 3.6
            Added ``session`` parameter.
-
         .. versionchanged:: 3.4
           Added the `collation` option.
-
         .. versionadded:: 3.0
         """
         write_concern = self._write_concern_for(session)
         return DeleteResult(
             self._delete_retryable(
                 filter, True,
                 write_concern=write_concern,
-                collation=collation, session=session),
+                collation=collation, hint=hint, session=session),
             write_concern.acknowledged)
 
     def find_one(self, filter=None, *args, **kwargs):
@@ -2849,10 +2871,8 @@ def inline_map_reduce(self, map, reduce, full_response=False, session=None,
 
         .. versionchanged:: 3.6
            Added ``session`` parameter.
-
         .. versionchanged:: 3.4
            Added the `collation` option.
-
         """
         res = self._map_reduce(map, reduce, {"inline": 1}, session,
                                self.read_preference, **kwargs)
@@ -2931,7 +2951,8 @@ def _find_and_modify(session, sock_info, retryable_write):
             write_concern.acknowledged, _find_and_modify, session)
 
     def find_one_and_delete(self, filter,
-                            projection=None, sort=None, session=None, **kwargs):
+                            projection=None, sort=None, hint=None,
+                            session=None, **kwargs):
         """Finds a single document and deletes it, returning the document.
 
           >>> db.test.count_documents({'x': 1})
@@ -2968,15 +2989,21 @@ def find_one_and_delete(self, filter,
           - `sort` (optional): a list of (key, direction) pairs
             specifying the sort order for the query. If multiple documents
             match the query, they are sorted and the first is deleted.
+          - `hint` (optional): 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)]``). This option is only supported
+            on MongoDB 4.4 and above.
           - `session` (optional): a
             :class:`~pymongo.client_session.ClientSession`.
           - `**kwargs` (optional): additional command arguments can be passed
             as keyword arguments (for example maxTimeMS can be used with
             recent server versions).
 
+        .. versionchanged:: 3.11
+           Added ``hint`` parameter.
         .. versionchanged:: 3.6
            Added ``session`` parameter.
-
         .. versionchanged:: 3.2
            Respects write concern.
 
@@ -2989,11 +3016,10 @@ def find_one_and_delete(self, filter,
         .. versionchanged:: 3.4
            Added the `collation` option.
         .. versionadded:: 3.0
-
         """
         kwargs['remove'] = True
         return self.__find_and_modify(filter, projection, sort,
-                                      session=session, **kwargs)
+                                      hint=hint, session=session, **kwargs)
 
     def find_one_and_replace(self, filter, replacement,
                              projection=None, sort=None, upsert=False,

pymongo/operations.py

@@ -57,9 +57,9 @@ def __ne__(self, other):
 class DeleteOne(object):
     """Represents a delete_one operation."""
 
-    __slots__ = ("_filter", "_collation")
+    __slots__ = ("_filter", "_collation", "_hint")
 
-    def __init__(self, filter, collation=None):
+    def __init__(self, filter, collation=None, hint=None):
         """Create a DeleteOne instance.
 
         For use with :meth:`~pymongo.collection.Collection.bulk_write`.
@@ -69,18 +69,31 @@ def __init__(self, filter, collation=None):
           - `collation` (optional): An instance of
             :class:`~pymongo.collation.Collation`. This option is only
             supported on MongoDB 3.4 and above.
+          - `hint` (optional): 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)]``). This option is only supported on
+            MongoDB 4.4 and above.
 
+        .. versionchanged:: 3.11
+           Added the ``hint`` option.
         .. versionchanged:: 3.5
            Added the `collation` option.
         """
         if filter is not None:
             validate_is_mapping("filter", filter)
+        if hint is not None:
+            if not isinstance(hint, string_type):
+                hint = helpers._index_document(hint)
         self._filter = filter
         self._collation = collation
+        self._hint = hint
 
     def _add_to_bulk(self, bulkobj):
         """Add this operation to the _Bulk instance `bulkobj`."""
-        bulkobj.add_delete(self._filter, 1, collation=self._collation)
+        bulkobj.add_delete(self._filter, 1, collation=self._collation,
+                           hint=self._hint)
 
     def __repr__(self):
         return "DeleteOne(%r, %r)" % (self._filter, self._collation)
@@ -98,9 +111,9 @@ def __ne__(self, other):
 class DeleteMany(object):
     """Represents a delete_many operation."""
 
-    __slots__ = ("_filter", "_collation")
+    __slots__ = ("_filter", "_collation", "_hint")
 
-    def __init__(self, filter, collation=None):
+    def __init__(self, filter, collation=None, hint=None):
         """Create a DeleteMany instance.
 
         For use with :meth:`~pymongo.collection.Collection.bulk_write`.
@@ -110,18 +123,31 @@ def __init__(self, filter, collation=None):
           - `collation` (optional): An instance of
             :class:`~pymongo.collation.Collation`. This option is only
             supported on MongoDB 3.4 and above.
+          - `hint` (optional): 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)]``). This option is only supported on
+            MongoDB 4.4 and above.
 
+        .. versionchanged:: 3.11
+           Added the ``hint`` option.
         .. versionchanged:: 3.5
            Added the `collation` option.
         """
         if filter is not None:
             validate_is_mapping("filter", filter)
+        if hint is not None:
+            if not isinstance(hint, string_type):
+                hint = helpers._index_document(hint)
         self._filter = filter
         self._collation = collation
+        self._hint = hint
 
     def _add_to_bulk(self, bulkobj):
         """Add this operation to the _Bulk instance `bulkobj`."""
-        bulkobj.add_delete(self._filter, 0, collation=self._collation)
+        bulkobj.add_delete(self._filter, 0, collation=self._collation,
+                           hint=self._hint)
 
     def __repr__(self):
         return "DeleteMany(%r, %r)" % (self._filter, self._collation)

test/crud/v2/aggregate-merge.json

@@ -1,7 +1,7 @@
 {
   "runOn": [
     {
-      "minServerVersion": "4.2.0"
+      "minServerVersion": "4.1.11"
     }
   ],
   "data": [