Add ability to delete documents by filter

meilisearch/errors.py

@@ -1,9 +1,16 @@
 from __future__ import annotations
 
 import json
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable
 
 from requests import Response
 
+if TYPE_CHECKING:
+    from meilisearch.client import Client
+    from meilisearch.index import Index
+    from meilisearch.task import TaskHandler
+
 
 class MeilisearchError(Exception):
     """Generic class for Meilisearch error handling"""
@@ -54,3 +61,15 @@ class MeilisearchTimeoutError(MeilisearchError):
 
     def __str__(self) -> str:
         return f"MeilisearchTimeoutError, {self.message}"
+
+
+def version_error_hint_message(func: Callable) -> Any:
+    @wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return func(*args, **kwargs)
+        except MeilisearchApiError as exc:
+            exc.message = f"{exc.message}. Hint: It might not be working because you're not up to date with the Meilisearch version that {func.__name__} call requires."
+            raise exc
+
+    return wrapper

meilisearch/index.py

@@ -6,6 +6,7 @@
 
 from meilisearch._httprequests import HttpRequests
 from meilisearch.config import Config
+from meilisearch.errors import version_error_hint_message
 from meilisearch.models.document import Document, DocumentsResults
 from meilisearch.models.index import Faceting, IndexStats, Pagination, TypoTolerance
 from meilisearch.models.task import Task, TaskInfo, TaskResults
@@ -729,12 +730,15 @@ def delete_document(self, document_id: Union[str, int]) -> TaskInfo:
         )
         return TaskInfo(**response)
 
-    def delete_documents(self, ids: List[Union[str, int]]) -> TaskInfo:
+    def delete_documents(
+        self,
+        ids: List[Union[str, int]],
+    ) -> TaskInfo:
         """Delete multiple documents from the index.
 
         Parameters
         ----------
-        list:
+        ids:
             List of unique identifiers of documents.
 
         Returns
@@ -754,6 +758,34 @@ def delete_documents(self, ids: List[Union[str, int]]) -> TaskInfo:
         )
         return TaskInfo(**response)
 
+    @version_error_hint_message
+    def delete_documents_by_filter(
+        self, filter: Union[str, List[Union[str, List[str]]]]  # pylint: disable=redefined-builtin
+    ) -> TaskInfo:
+        """Delete documents from the index by filter.
+
+        Parameters
+        ----------
+        filter:
+            The filter value information.
+
+        Returns
+        -------
+        task_info:
+            TaskInfo instance containing information about a task to track the progress of an asynchronous process.
+            https://docs.meilisearch.com/reference/api/tasks.html#get-one-task
+
+        Raises
+        ------
+        MeilisearchApiError
+            An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://docs.meilisearch.com/errors/#meilisearch-errors
+        """
+        response = self.http.post(
+            f"{self.config.paths.index}/{self.uid}/{self.config.paths.document}/delete",
+            body={"filter": filter},
+        )
+        return TaskInfo(**response)
+
     def delete_all_documents(self) -> TaskInfo:
         """Delete all documents from the index.
 

meilisearch/models/document.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from typing import Any, Dict, Iterator
 
 

tests/errors/test_api_error_meilisearch.py

@@ -6,7 +6,7 @@
 import requests
 
 import meilisearch
-from meilisearch.errors import MeilisearchApiError
+from meilisearch.errors import MeilisearchApiError, version_error_hint_message
 from tests import BASE_URL, MASTER_KEY
 
 
@@ -33,3 +33,22 @@ def test_meilisearch_api_error_no_code(mock_post):
     with pytest.raises(MeilisearchApiError):
         client = meilisearch.Client(BASE_URL, MASTER_KEY + "123")
         client.create_index("some_index")
+
+
+def test_version_error_hint_message():
+    mock_response = requests.models.Response()
+    mock_response.status_code = 408
+
+    class FakeClass:
+        @version_error_hint_message
+        def test_method(self):
+            raise MeilisearchApiError("This is a test", mock_response)
+
+    with pytest.raises(MeilisearchApiError) as e:
+        fake = FakeClass()
+        fake.test_method()
+
+    assert (
+        "MeilisearchApiError. This is a test. Hint: It might not be working because you're not up to date with the Meilisearch version that test_method call requires."
+        == str(e.value)
+    )

tests/index/test_index_document_meilisearch.py

@@ -174,6 +174,20 @@ def test_delete_documents(index_with_documents):
             index.get_document(document)
 
 
+def test_delete_documents_by_filter(index_with_documents):
+    index = index_with_documents()
+    response = index.update_filterable_attributes(["genre"])
+    index.wait_for_task(response.task_uid)
+    response = index.get_documents()
+    assert "action" in ([x.__dict__.get("genre") for x in response.results])
+    response = index.delete_documents_by_filter("genre=action")
+    index.wait_for_task(response.task_uid)
+    response = index.get_documents()
+    genres = [x.__dict__.get("genre") for x in response.results]
+    assert "action" not in genres
+    assert "cartoon" in genres
+
+
 def test_delete_all_documents(index_with_documents):
     """Tests deleting all the documents in the index."""
     index = index_with_documents()