Merge #1063

1063: Support searching for similar documents r=sanders41 a=ellnix

# Pull Request

## Related issue
Fixes #988

Instructions were not to add the `GET` endpoint, it seems other integrations also do not have it.

I tried as closely as possible to match the documentation and the signature of the main `search` method. If I should wrap the results in a class, please let me know once again and I'll do it.

Co-authored-by: ellnix <ellnix@disroot.org>

Author: meili-bors[bot]

.code-samples.meilisearch.yaml

@@ -751,3 +751,5 @@ get_all_batches_1: |-
   client.get_batches()
 get_batch_1: |-
   client.get_batch(BATCH_UID)
+get_similar_post_1: |-
+  client.index("INDEX_NAME").get_similar_documents({"id": "TARGET_DOCUMENT_ID", "embedder": "default"})

meilisearch/config.py

@@ -20,6 +20,7 @@ class Paths:
         facet_search = "facet-search"
         multi_search = "multi-search"
         document = "documents"
+        similar = "similar"
         setting = "settings"
         ranking_rules = "ranking-rules"
         distinct_attribute = "distinct-attribute"

meilisearch/index.py

@@ -406,6 +406,30 @@ def get_documents(
         )
         return DocumentsResults(response)
 
+    def get_similar_documents(self, parameters: Mapping[str, Any]) -> Dict[str, Any]:
+        """Get the documents similar to a document.
+
+        Parameters
+        ----------
+        parameters:
+            parameters accepted by the get similar documents route: https://www.meilisearch.com/docs/reference/api/similar#body
+            "id" and "embedder" are required.
+
+        Returns
+        -------
+        results:
+            Dictionary with hits, offset, limit, processingTimeMs, and id
+
+        Raises
+        ------
+        MeilisearchApiError
+            An error containing details about why Meilisearch can't process your request. Meilisearch error codes are described here: https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
+        """
+        return self.http.post(
+            f"{self.config.paths.index}/{self.uid}/{self.config.paths.similar}",
+            body=parameters,
+        )
+
     def add_documents(
         self,
         documents: Sequence[Mapping[str, Any]],

tests/index/test_index_document_meilisearch.py

@@ -266,6 +266,32 @@ def test_get_documents_filter_with_fields(index_with_documents):
     assert next(iter(genres)) == "action"
 
 
+@pytest.mark.usefixtures("enable_vector_search")
+def test_get_similar_documents(empty_index):
+    index = empty_index()
+    index.update_embedders({"manual": {"source": "userProvided", "dimensions": 3}})
+
+    hp3 = {
+        "id": 1,
+        "title": "Harry Potter and the Prisoner of Azkaban",
+        "_vectors": {"manual": [0.8, 0.8, 0.8]},
+    }
+    hp4 = {
+        "id": 2,
+        "title": "Harry Potter and the Goblet of Fire",
+        "_vectors": {"manual": [0.7, 0.7, 0.9]},
+    }
+    lotr = {"id": 3, "title": "The Lord of the Rings", "_vectors": {"manual": [0.6, 0.5, 0.2]}}
+
+    addition = index.add_documents([hp3, hp4, lotr])
+    index.wait_for_task(addition.task_uid)
+
+    similars = index.get_similar_documents({"id": hp4["id"], "embedder": "manual"})
+
+    assert similars["hits"][0]["id"] == hp3["id"]
+    assert similars["hits"][1]["id"] == lotr["id"]
+
+
 def test_update_documents(index_with_documents, small_movies):
     """Tests updating a single document and a set of documents."""
     index = index_with_documents()