From 5387ed00d29a43ff704791179371103c432d833d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christoph=20B=C3=BCscher?= Date: Fri, 14 Jul 2017 18:33:28 +0200 Subject: [PATCH] [Docs] Adding suggestion sections to high level client docs (#25724) This adds a section about how to add suggestions to the SearchSourceBuilder and how to retrieve them from a SearchResponse. --- .../documentation/SearchDocumentationIT.java | 50 ++++++++++++++++++- .../java-rest/high-level/apis/search.asciidoc | 34 ++++++++++++- 2 files changed, 82 insertions(+), 2 deletions(-) diff --git a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java index 02cc13ecc5f..5b6ad3a334d 100644 --- a/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java +++ b/client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SearchDocumentationIT.java @@ -51,6 +51,11 @@ import org.elasticsearch.search.aggregations.metrics.avg.Avg; import org.elasticsearch.search.builder.SearchSourceBuilder; import org.elasticsearch.search.sort.ScoreSortBuilder; import org.elasticsearch.search.sort.SortOrder; +import org.elasticsearch.search.suggest.Suggest; +import org.elasticsearch.search.suggest.SuggestBuilder; +import org.elasticsearch.search.suggest.SuggestBuilders; +import org.elasticsearch.search.suggest.SuggestionBuilder; +import org.elasticsearch.search.suggest.term.TermSuggestion; import java.io.IOException; import java.util.Arrays; @@ -207,7 +212,7 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { } } - @SuppressWarnings({ "unused", "unchecked" }) + @SuppressWarnings({ "unused" }) public void testSearchRequestAggregations() throws IOException { RestHighLevelClient client = highLevelClient(); { @@ -282,6 +287,49 @@ public class SearchDocumentationIT extends ESRestHighLevelClientTestCase { } } + @SuppressWarnings({ "unused", "rawtypes" }) + public void testSearchRequestSuggestions() throws IOException { + RestHighLevelClient client = highLevelClient(); + { + BulkRequest request = new BulkRequest(); + request.add(new IndexRequest("posts", "doc", "1").source(XContentType.JSON, "user", "kimchy")); + request.add(new IndexRequest("posts", "doc", "2").source(XContentType.JSON, "user", "javanna")); + request.add(new IndexRequest("posts", "doc", "3").source(XContentType.JSON, "user", "tlrx")); + request.add(new IndexRequest("posts", "doc", "4").source(XContentType.JSON, "user", "cbuescher")); + request.setRefreshPolicy(WriteRequest.RefreshPolicy.IMMEDIATE); + BulkResponse bulkResponse = client.bulk(request); + assertSame(bulkResponse.status(), RestStatus.OK); + assertFalse(bulkResponse.hasFailures()); + } + { + SearchRequest searchRequest = new SearchRequest(); + // tag::search-request-suggestion + SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder(); + SuggestionBuilder termSuggestionBuilder = + SuggestBuilders.termSuggestion("user").text("kmichy"); // <1> + SuggestBuilder suggestBuilder = new SuggestBuilder(); + suggestBuilder.addSuggestion("suggest_user", termSuggestionBuilder); // <2> + searchSourceBuilder.suggest(suggestBuilder); + // end::search-request-suggestion + searchRequest.source(searchSourceBuilder); + SearchResponse searchResponse = client.search(searchRequest); + { + // tag::search-request-suggestion-get + Suggest suggest = searchResponse.getSuggest(); // <1> + TermSuggestion termSuggestion = suggest.getSuggestion("suggest_user"); // <2> + for (TermSuggestion.Entry entry : termSuggestion.getEntries()) { // <3> + for (TermSuggestion.Entry.Option option : entry) { // <4> + String suggestText = option.getText().string(); + } + } + // end::search-request-suggestion-get + assertEquals(1, termSuggestion.getEntries().size()); + assertEquals(1, termSuggestion.getEntries().get(0).getOptions().size()); + assertEquals("kimchy", termSuggestion.getEntries().get(0).getOptions().get(0).getText().string()); + } + } + } + public void testScroll() throws IOException { RestHighLevelClient client = highLevelClient(); { diff --git a/docs/java-rest/high-level/apis/search.asciidoc b/docs/java-rest/high-level/apis/search.asciidoc index d2d0e71d539..1ccf1566ae3 100644 --- a/docs/java-rest/high-level/apis/search.asciidoc +++ b/docs/java-rest/high-level/apis/search.asciidoc @@ -96,6 +96,23 @@ include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregatio We will later see how to <> in the `SearchResponse`. +===== Requesting Suggestions + +To add Suggestions to the search request, use one of the `SuggestionBuilder` implementations +that are easily accessible from the `SuggestBuilders` factory class. Suggestion builders +need to be added to the top level `SuggestBuilder`, which itself can be set on the `SearchSourceBuilder`. + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-suggestion] +-------------------------------------------------- +<1> Creates a new `TermSuggestionBuilder` for the `user` field and +the text `kmichy` +<2> Adds the suggestion builder and names it `suggest_user` + +We will later see how to <> from the +`SearchResponse`. + [[java-rest-high-document-search-sync]] ==== Synchronous Execution @@ -241,4 +258,19 @@ decide how to further process them based on their type: ["source","java",subs="attributes,callouts,macros"] -------------------------------------------------- include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-aggregations-iterator] --------------------------------------------------- \ No newline at end of file +-------------------------------------------------- + +[[java-rest-high-retrieve-suggestions]] +===== Retrieving Suggestions + +To get back the suggestions from a `SearchResponse`, use the `Suggest` object as an entry point and then retrieve the nested suggestion objects: + +["source","java",subs="attributes,callouts,macros"] +-------------------------------------------------- +include-tagged::{doc-tests}/SearchDocumentationIT.java[search-request-suggestion-get] +-------------------------------------------------- +<1> Use the `Suggest` class to access suggestions +<2> Suggestions can be retrieved by name. You need to assign them to the correct +type of Suggestion class (here `TermSuggestion`), otherwise a `ClassCastException` is thrown +<3> Iterate over the suggestion entries +<4> Iterate over the options in one entry