Implement facet_search

Author: LeoErcolanelli

algoliasearch/index.py

@@ -904,6 +904,24 @@ def batch(self, requests, no_create=False):
 
         return self._req(False, '/batch', 'POST', data=requests)
 
+    def search_facet(self, facet_name, facet_query, query=None):
+        """
+        Perform a search within a given facet's values
+        @param facet_name name of the facet to search. It must have been
+            declared in the index's `attributesForFacetting` setting with the
+            `searchable()` modifier.
+        @param facet_query text to search for in the facet's values.
+        @param query an optional query to take extra search parameters into
+            account. The parameters apply to index objects like in a regular
+            search query. Only facet values contained in the matched objects
+            will be returned.
+        """
+        if query is None:
+            query = {}
+        query['facetQuery'] = facet_query
+        path = '/facets/%s/query' % safe(facet_name)
+        return self._req(True, path, 'POST', data={'params' : urlencode(urlify(query))})
+
     def _req(self, is_search, path, meth, params=None, data=None):
         """Perform an HTTPS request with retry logic."""
         path = '%s%s' % (self._request_path, path)

tests/test_index.py

@@ -135,6 +135,61 @@ def test_synonyms(self):
         task = self.index.search_synonyms('', hits_per_page=5)
         self.assertEqual(0, int(task['nbHits']))
 
+    def test_facet_search(self):
+        settings = {'attributesForFacetting': ['searchable(series)', 'kind']}
+        objects = [
+             {
+                 'objectID': '1',
+                 'name': 'Snoopy',
+                 'kind': [ 'dog', 'animal' ],
+                 'born': 1950,
+                 'series': 'Peanuts'
+             },
+             {
+                 'objectID': '2',
+                 'name': 'Woodstock',
+                 'kind': ['bird', 'animal' ],
+                 'born': 1960,
+                 'series': 'Peanuts'
+             },
+             {
+                 'objectID': '3',
+                 'name': 'Charlie Brown',
+                 'kind': [ 'human' ],
+                 'born': 1950,
+                 'series': 'Peanuts'
+             },
+            {
+                'objectID': '4',
+                'name': 'Hobbes',
+                'kind': ['tiger', 'animal', 'teddy' ],
+                'born': 1985,
+                'series': 'Calvin & Hobbes'
+            },
+            {
+                'objectID': '5',
+                'name': 'Calvin',
+                'kind': [ 'human' ],
+                'born': 1985,
+                'series': 'Calvin & Hobbes'
+             }
+         ]
+
+        self.index.set_settings(settings)
+        task = self.index.add_objects(objects)
+        self.index.wait_task(task['taskID'])
+
+        # Straightforward search.
+        facetHits = self.index.search_facet('series', 'Hobb')['facetHits']
+        self.assertEqual(len(facetHits), 1)
+        self.assertEqual(facetHits[0]['value'], 'Calvin & Hobbes')
+        self.assertEqual(facetHits[0]['count'], 2)
+
+        # Using an addition query to restrict search.
+        query = {'facetFilters': 'kind:animal', 'numericFilters': 'born >= 1955'}
+        facetHits = self.index.search_facet('series', 'Peanutz', query)['facetHits']
+        self.assertEqual(facetHits[0]['value'], 'Peanuts')
+        self.assertEqual(facetHits[0]['count'], 1)
 
 class IndexWithReadOnlyDataTest(IndexTest):
     """Tests that use one index with initial data (read only)."""