Add support for search in facet values (#140)

* Add support for search in facet values

- Add a new method `Index.searchFacet(_:for:query:completionHandler:)` targeting the `POST /1/indexes/${indexName}/facets/${facetName}/query/` API endpoint.
- Swift unit test
- Objective-C bridging test

* [doc] Fix typo

* Rename `searchFacet(…)` to `searchForFacetValues(…)`

… to match the new official naming and the other API clients.

Author: Clément Le Provost

Source/Index.swift

@@ -363,6 +363,30 @@ import Foundation
         }
     }
 
+    /// Search for facet values.
+    /// This searches inside a facet's values, optionally restricting the returned values to those contained in objects
+    /// matching other (regular) search criteria.
+    ///
+    /// - parameter facetName: Name of the facet to search. It must have been declared in the index's
+    ///       `attributesForFaceting` setting with the `searchable()` modifier.
+    /// - parameter text: Text to search for in the facet's values.
+    /// - parameter query: An optional query to take extra search parameters into account. These parameters apply to
+    ///       index objects like in a regular search query. Only facet values contained in the matched objects will be
+    ///       returned.
+    /// - parameter completionHandler: Completion handler to be notified of the request's outcome.
+    /// - returns: A cancellable operation.
+    ///
+    @objc(searchForFacetValuesOf:matching:query:completionHandler:)
+    @discardableResult public func searchForFacetValues(of facetName: String, matching text: String, query: Query? = nil, completionHandler: @escaping CompletionHandler) -> Operation {
+        let path = "1/indexes/\(urlEncodedName)/facets/\(facetName.urlEncodedPathComponent())/query"
+        let params = query != nil ? Query(copy: query!) : Query()
+        params["facetQuery"] = text
+        let requestBody = [
+            "params": params.build()
+        ]
+        return client.performHTTPQuery(path: path, method: .POST, body: requestBody, hostnames: client.readHosts, isSearchQuery: true, completionHandler: completionHandler)
+    }
+    
     /// Get this index's settings.
     ///
     /// - parameter completionHandler: Completion handler to be notified of the request's outcome.

Tests/IndexTests.swift

@@ -1158,4 +1158,82 @@ class IndexTests: OnlineTestCase {
         }
         self.waitForExpectations(timeout: expectationTimeout + timeout * 4, handler: nil)
     }
+    
+    func testSearchForFacetValues() {
+        let expectation = self.expectation(description: #function)
+        let settings = [
+            "attributesForFaceting": [
+                "searchable(series)",
+                "kind"
+            ]
+        ]
+        let objects: [String: JSONObject] = [
+            "snoopy": [
+                "objectID": "1",
+                "name": "Snoopy",
+                "kind": [ "dog", "animal" ],
+                "born": 1950,
+                "series": "Peanuts"
+            ],
+            "woodstock": [
+                "objectID": "2",
+                "name": "Woodstock",
+                "kind": ["bird", "animal" ],
+                "born": 1960,
+                "series": "Peanuts"
+            ],
+            "charlie": [
+                "objectID": "3",
+                "name": "Charlie Brown",
+                "kind": [ "human" ],
+                "born": 1950,
+                "series": "Peanuts"
+            ],
+            "hobbes": [
+                "objectID": "4",
+                "name": "Hobbes",
+                "kind": [ "tiger", "animal", "teddy" ],
+                "born": 1985,
+                "series": "Calvin & Hobbes"
+            ],
+            "calvin": [
+                "objectID": "5",
+                "name": "Calvin",
+                "kind": [ "human" ],
+                "born": 1985,
+                "series": "Calvin & Hobbes"
+            ]
+        ]
+        
+        // Populate index.
+        index.setSettings(settings) { (content, error) in
+            guard error == nil else { XCTFail(error!.localizedDescription); expectation.fulfill(); return }
+            self.index.addObjects(Array(objects.values)) { (content, error) in
+                guard error == nil, let taskID = content!["taskID"] as? Int else { XCTFail(error!.localizedDescription); expectation.fulfill(); return }
+                self.index.waitTask(withID: taskID) { (content, error) in
+                    guard error == nil else { XCTFail(error!.localizedDescription); expectation.fulfill(); return }
+                    // Query with no extra search parameters.
+                    self.index.searchForFacetValues(of: "series", matching: "Hobb") { (content, error) in
+                        guard error == nil else { XCTFail(error!.localizedDescription); expectation.fulfill(); return }
+                        guard let facetHits = content!["facetHits"] as? [JSONObject] else { XCTFail("No facet hits"); expectation.fulfill(); return }
+                        XCTAssertEqual(facetHits.count, 1)
+                        XCTAssertEqual(facetHits[0]["value"] as? String, "Calvin & Hobbes")
+                        XCTAssertEqual(facetHits[0]["count"] as? Int, 2)
+                        // Query with extra search parameters.
+                        let query = Query()
+                        query.facetFilters = ["kind:animal"]
+                        query.numericFilters = ["born >= 1955"]
+                        self.index.searchForFacetValues(of: "series", matching: "Peanutz", query: query) { (content, error) in
+                            guard error == nil else { XCTFail(error!.localizedDescription); expectation.fulfill(); return }
+                            guard let facetHits = content!["facetHits"] as? [JSONObject] else { XCTFail("No facet hits"); expectation.fulfill(); return }
+                            XCTAssertEqual(facetHits[0]["value"] as? String, "Peanuts")
+                            XCTAssertEqual(facetHits[0]["count"] as? Int, 1)
+                            expectation.fulfill()
+                        }
+                    }
+                }
+            }
+        }
+        self.waitForExpectations(timeout: expectationTimeout, handler: nil)
+    }
 }

Tests/ObjectiveCBridging.m

@@ -237,6 +237,9 @@ - (void)testIndex {
     [index search:[Query new] completionHandler:^(NSDictionary<NSString*,id>* content, NSError* error) {
         // Do nothing.
     }];
+    [index searchForFacetValuesOf:@"facet" matching:@"text" query:nil completionHandler:^(NSDictionary<NSString *,id>* content, NSError* error) {
+        // Do nothing.
+    }];
     [index getSettings:^(NSDictionary<NSString*,id>* content, NSError* error) {
         // Do nothing.
     }];