Merge #839

839: Support search in facet values r=sanders41 a=cyprx

# Pull Request

## Related issue
Fixes #830 

## What does this PR do?
- Add function `facet_search` which performs search in facet values
- Add code samples
- Add integration tests

## PR checklist
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


Co-authored-by: cyprx <[email protected]>
Co-authored-by: Paul Sanders <[email protected]>

Author: 3 people

.code-samples.meilisearch.yaml

@@ -695,3 +695,9 @@ date_guide_sort_1: |-
   client.index('games').search('', {
     'sort': ['release_timestamp:desc']
   })
+facet_search_1: |-
+  client.index('books').facet_search('fiction', 'genres', {
+    'filter': 'rating > 3'
+  })
+facet_search_3: |-
+  client.index('books').facet_search('c', 'genres')

meilisearch/config.py

@@ -16,6 +16,7 @@ class Paths:
         task = "tasks"
         stat = "stats"
         search = "search"
+        facet_search = "facet-search"
         multi_search = "multi-search"
         document = "documents"
         setting = "settings"

meilisearch/index.py

@@ -279,6 +279,39 @@ def search(self, query: str, opt_params: Optional[Dict[str, Any]] = None) -> Dic
             body=body,
         )
 
+    @version_error_hint_message
+    def facet_search(
+        self,
+        facet_name: str,
+        facet_query: Optional[str] = None,
+        opt_params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Perform a facet search based on the given facet query and facet name.
+
+        Parameters
+        ----------
+        facet_name:
+            String containing the name of the facet on which the search is performed.
+        facet_query (optional):
+            String containing the searched words
+        opt_params (optional):
+            Dictionary containing optional query parameters.
+
+        Returns
+        -------
+        results:
+            Dictionary with facetHits, processingTime and initial facet query
+
+        """
+        if opt_params is None:
+            opt_params = {}
+        body = {"facetName": facet_name, "facetQuery": facet_query, **opt_params}
+        return self.http.post(
+            f"{self.config.paths.index}/{self.uid}/{self.config.paths.facet_search}",
+            body=body,
+        )
+
     def get_document(
         self, document_id: Union[str, int], parameters: Optional[Dict[str, Any]] = None
     ) -> Document:

tests/conftest.py

@@ -140,6 +140,19 @@ def index_maker(index_uid=common.INDEX_UID, documents=small_movies):
     return index_maker
 
 
+@fixture(scope="function")
+def index_with_documents_and_facets(empty_index, small_movies):
+    def index_maker(index_uid=common.INDEX_UID, documents=small_movies):
+        index = empty_index(index_uid)
+        task_1 = index.update_filterable_attributes(["genre"])
+        index.wait_for_task(task_1.task_uid)
+        task_2 = index.add_documents(documents)
+        index.wait_for_task(task_2.task_uid)
+        return index
+
+    return index_maker
+
+
 @fixture(scope="function")
 def test_key(client):
     key_info = {

tests/index/test_index_facet_search_meilisearch .py

@@ -0,0 +1,48 @@
+# pylint: disable=invalid-name
+
+
+def test_basic_facet_search(index_with_documents_and_facets):
+    """Tests facet search with a simple query."""
+    response = index_with_documents_and_facets().facet_search("genre", "cartoon")
+    assert isinstance(response, dict)
+    assert response["facetHits"][0]["count"] == 3
+    assert response["facetQuery"] == "cartoon"
+
+
+def test_facet_search_with_empty_query(index_with_documents_and_facets):
+    """Tests facet search with a empty query."""
+    response = index_with_documents_and_facets().facet_search("genre")
+    assert isinstance(response, dict)
+    assert len(response["facetHits"]) == 4
+    assert response["facetHits"][0]["value"] == "action"
+    assert response["facetHits"][1]["count"] == 3
+    assert response["facetQuery"] is None
+
+
+def test_facet_search_with_q(index_with_documents_and_facets):
+    """Tests facet search with a keyword query q."""
+    response = index_with_documents_and_facets().facet_search("genre", "cartoon", {"q": "dragon"})
+    assert isinstance(response, dict)
+    assert response["facetHits"][0]["count"] == 1
+    assert response["facetQuery"] == "cartoon"
+
+
+def test_facet_search_with_filter(index_with_documents_and_facets):
+    """Tests facet search with a filter."""
+    index = index_with_documents_and_facets()
+    task = index.update_filterable_attributes(["genre", "release_date"])
+    index.wait_for_task(task.task_uid)
+    response = index.facet_search("genre", "cartoon", {"filter": "release_date > 1149728400"})
+    assert isinstance(response, dict)
+    assert response["facetHits"][0]["count"] == 2
+    assert response["facetQuery"] == "cartoon"
+
+
+def test_facet_search_with_attributes_to_search_on(index_with_documents_and_facets):
+    """Tests facet search with optional parameter attributesToSearchOn."""
+    response = index_with_documents_and_facets().facet_search(
+        "genre", "action", {"q": "aquaman", "attributesToSearchOn": ["overview"]}
+    )
+    assert isinstance(response, dict)
+    assert len(response["facetHits"]) == 0
+    assert response["facetQuery"] == "action"