Index: Implement search in facets (#163)

* Index: Implement search in facets

* Index: Overload searchFacet for query-less usage

* Index.searchFacet: Add NonNull annotations, more explicit code/parameter name

* Index.searchForFacetValues: Rename from searchFacet

* Travis: use travis_wait to investigate CI failures

* IndexTest: Fix typo [ci skip]

Author: PLNech

algoliasearch/src/main/java/com/algolia/search/saas/Index.java

@@ -181,6 +181,47 @@ protected Request multipleQueriesAsync(@NonNull List<Query> queries, @NonNull Co
         }.searchDisjunctiveFacetingAsync(query, disjunctiveFacets, refinements, completionHandler);
     }
 
+    /**
+     * Search for some text in a facet values.
+     *
+     * @param facetName The name of the facet to search. It must have been declared in the index's `attributesForFaceting` setting with the `searchable()` modifier.
+     * @param text      The text to search for in the facet's values.
+     * @param handler   A Completion handler that will be notified of the request's outcome.
+     * @return A cancellable request.
+     */
+    public Request searchForFacetValues(@NonNull String facetName, @NonNull String text, @NonNull final CompletionHandler handler) throws AlgoliaException {
+        return searchForFacetValues(facetName, text, null, handler);
+    }
+
+    /**
+     * Search for some text in a facet values, optionally restricting the returned values to those contained in objects matching other (regular) search criteria.
+     *
+     * @param facetName The name of the facet to search. It must have been declared in the index's `attributesForFaceting` setting with the `searchable()` modifier.
+     * @param facetText      The text to search for in the facet's values.
+     * @param query     An optional query to take extra search parameters into account. There parameters apply to index objects like in a regular search query. Only facet values contained in the matched objects will be returned
+     * @param handler   A Completion handler that will be notified of the request's outcome.
+     * @return A cancellable request.
+     */
+    public Request searchForFacetValues(@NonNull String facetName, @NonNull String facetText, @Nullable Query query, @NonNull final CompletionHandler handler) throws AlgoliaException {
+        try {
+            final String path = "/1/indexes/" + getEncodedIndexName() + "/facets/" + URLEncoder.encode(facetName, "UTF-8") + "/query";
+            final Query params = (query != null ? new Query(query) : new Query());
+            params.set("facetQuery", facetText);
+            final JSONObject requestBody = new JSONObject().put("params", params.build());
+
+            final Client client = getClient();
+            return client.new AsyncTaskRequest(handler) {
+                @NonNull
+                @Override
+                protected JSONObject run() throws AlgoliaException {
+                    return client.postRequest(path, requestBody.toString(), true);
+                }
+            }.start();
+        } catch (UnsupportedEncodingException | JSONException e) {
+            throw new AlgoliaException(e.getMessage());
+        }
+    }
+
     /**
      * Add an object to this index (asynchronously).
      * <p>
@@ -274,7 +315,7 @@ public Request saveObjectsAsync(final @NonNull JSONArray objects, @NonNull Compl
 
     /**
      * Partially update an object (asynchronously).
-     *
+     * <p>
      * **Note:** This method will create the object if it does not exist already. If you don't wish to, you can use
      * {@link #partialUpdateObjectAsync(JSONObject, String, boolean, CompletionHandler)} and specify `false` for the
      * `createIfNotExists` argument.
@@ -313,7 +354,7 @@ public Request partialUpdateObjectAsync(final @NonNull JSONObject partialObject,
 
     /**
      * Partially update several objects (asynchronously).
-     *
+     * <p>
      * **Note:** This method will create the objects if they do not exist already. If you don't wish to, you can use
      * {@link #partialUpdateObjectsAsync(JSONArray, boolean, CompletionHandler)} and specify `false` for the
      * `createIfNotExists` argument.
@@ -500,7 +541,7 @@ public Request getSettingsAsync(@NonNull CompletionHandler completionHandler) {
 
     /**
      * Set this index's settings (asynchronously).
-     *
+     * <p>
      * Please refer to our <a href="https://www.algolia.com/doc/android#index-settings">API documentation</a> for the
      * list of supported settings.
      *
@@ -1029,7 +1070,7 @@ protected JSONObject setSettings(JSONObject settings) throws AlgoliaException {
     /**
      * Set settings for this index.
      *
-     * @param settings        the settings object.
+     * @param settings          the settings object.
      * @param forwardToReplicas if true, the new settings will be forwarded to replica indices.
      * @throws AlgoliaException
      */

algoliasearch/src/test/java/com/algolia/search/saas/IndexTest.java

@@ -1031,4 +1031,86 @@ public void doRequestCompleted(JSONObject content, AlgoliaException error) {
             }
         });
     }
+
+    @Test
+    public void searchForFacFacetValues() throws Exception {
+        final JSONObject setSettingsTask = index.setSettings(new JSONObject()
+                .put("attributesForFaceting", new JSONArray()
+                        .put("searchable(series)")
+                        .put("kind"))
+        );
+
+        final JSONObject addObjectsResult = index.addObjects(new JSONArray()
+                .put(new JSONObject()
+                        .put("objectID", "1")
+                        .put("name", "Snoopy")
+                        .put("kind", new JSONArray().put("dog").put("animal"))
+                        .put("born", 1950)
+                        .put("series", "Peanuts"))
+                .put(new JSONObject()
+                        .put("objectID", "2")
+                        .put("name", "Woodstock")
+                        .put("kind", new JSONArray().put("bird").put("animal"))
+                        .put("born", 1960)
+                        .put("series", "Peanuts"))
+                .put(new JSONObject()
+                        .put("objectID", "3")
+                        .put("name", "Charlie Brown")
+                        .put("kind", new JSONArray().put("human"))
+                        .put("born", 1950)
+                        .put("series", "Peanuts"))
+                .put(new JSONObject()
+                        .put("objectID", "4")
+                        .put("name", "Hobbes")
+                        .put("kind", new JSONArray().put("tiger").put("animal").put("teddy"))
+                        .put("born", 1985)
+                        .put("series", "Calvin & Hobbes"))
+                .put(new JSONObject()
+                        .put("objectID", "5")
+                        .put("name", "Calvin")
+                        .put("kind", new JSONArray().put("human"))
+                        .put("born", 1985)
+                        .put("series", "Calvin & Hobbes"))
+        );
+
+        index.waitTask(setSettingsTask.getString("taskID"));
+        index.waitTask(addObjectsResult.getString("taskID"));
+
+        index.searchForFacetValues("series", "Hobb", null, new AssertCompletionHandler() {
+            @Override
+            public void doRequestCompleted(JSONObject content, AlgoliaException error) {
+                assertNull("There should be no error", error);
+                final JSONArray facetHits = content.optJSONArray("facetHits");
+                assertTrue("The response should have facetHits.", facetHits != null);
+                try {
+                    assertEquals("There should be one facet match.", 1, facetHits.length());
+                    JSONObject result = facetHits.getJSONObject(0);
+                    assertEquals("The serie should be Calvin & Hobbes.", "Calvin & Hobbes", result.getString("value"));
+                    assertEquals("Two results should have matched.", 2, result.getInt("count"));
+                } catch (JSONException e) {
+                    fail(e.toString());
+                }
+            }
+        });
+
+        Query query = new Query()
+                .setFacetFilters(new JSONArray().put("kind:animal"))
+                .setNumericFilters(new JSONArray().put("born >= 1955"));
+        index.searchForFacetValues("series", "Peanutz", query, new AssertCompletionHandler() {
+            @Override
+            public void doRequestCompleted(JSONObject content, AlgoliaException error) {
+                assertNull("There should be no error", error);
+                final JSONArray facetHits = content.optJSONArray("facetHits");
+                assertTrue("The response should have facetHits.", facetHits != null);
+                try {
+                    assertEquals("There should be one facet match.", 1, facetHits.length());
+                    JSONObject result = facetHits.getJSONObject(0);
+                    assertEquals("The serie should be Peanuts.", "Peanuts", result.getString("value"));
+                    assertEquals("Two results should have matched.", 1, result.getInt("count"));
+                } catch (JSONException e) {
+                    fail(e.getMessage());
+                }
+            }
+        });
+    }
 }