Add documentation for templated search (#362) (#365)

Co-authored-by: Sylvain Wallez <[email protected]>

docs/usage/searching.asciidoc

@@ -43,4 +43,29 @@ include-tagged::{doc-tests-src}/usage/SearchingTest.java[search-nested]
 <4> The search query is a boolean query that combines the text search and max price queries.
 <5> Both queries are added as `must` as we want results to match all criteria.
 
+[discrete]
+==== Templated search
+
+A search template is a stored search that you can run with different variables. Search templates let you change your searches without modifying your application code.
+
+Before running a template search, you first have to create the template. This is a stored script that returns the search request body, and is usually defined as a Mustache template. This stored script can be created outside the application, and also with the {java-client}:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/SearchingTest.java[search-template-script]
+--------------------------------------------------
+<1> Identifier of the template script to create.
+
+To use the search template, use the `searchTemplate` method to refer to the script and provide values for its parameters:
+
+["source","java"]
+--------------------------------------------------
+include-tagged::{doc-tests-src}/usage/SearchingTest.java[search-template-query]
+--------------------------------------------------
+<1> Identifier of the template script to use.
+<2> Template parameter values.
+
+For more in-depth information, see the {es-docs}/search-template.html[{es} search template documentation].
+
+
 {doc-tests-blurb}

java-client/src/test/java/co/elastic/clients/documentation/usage/SearchingTest.java

@@ -24,7 +24,9 @@
 import co.elastic.clients.elasticsearch._types.query_dsl.MatchQuery;
 import co.elastic.clients.elasticsearch._types.query_dsl.Query;
 import co.elastic.clients.elasticsearch._types.query_dsl.RangeQuery;
+import co.elastic.clients.elasticsearch.core.PutScriptResponse;
 import co.elastic.clients.elasticsearch.core.SearchResponse;
+import co.elastic.clients.elasticsearch.core.SearchTemplateResponse;
 import co.elastic.clients.elasticsearch.core.search.Hit;
 import co.elastic.clients.elasticsearch.core.search.TotalHits;
 import co.elastic.clients.elasticsearch.core.search.TotalHitsRelation;
@@ -133,4 +135,43 @@ public void searchNested() throws Exception {
         }
         //end::search-nested
     }
+
+    @Test
+    public void searchTemplate() throws Exception {
+
+        transport.setResult(PutScriptResponse.of(r -> r.acknowledged(true)));
+
+        //tag::search-template-script
+        // Create a script
+        esClient.putScript(r -> r
+            .id("query-script") // <1>
+            .script(s -> s
+                .lang("mustache")
+                .source("{\"query\":{\"match\":{\"{{field}}\":\"{{value}}\"}}}")
+            ));
+        //end::search-template-script
+
+        transport.setResult(SearchTemplateResponse.<JsonData>of(r -> r
+            .hits(searchResponse.hits())
+            .took(searchResponse.took())
+            .timedOut(false)
+            .shards(searchResponse.shards())
+        ));
+
+        //tag::search-template-query
+        SearchTemplateResponse<Product> response = esClient.searchTemplate(r -> r
+                .index("some-index")
+                .id("query-script") // <1>
+                .params("field", JsonData.of("some-field")) // <2>
+                .params("value", JsonData.of("some-data")),
+            Product.class
+        );
+
+        List<Hit<Product>> hits = response.hits().hits();
+        for (Hit<Product> hit: hits) {
+            Product product = hit.source();
+            logger.info("Found product " + product.getSku() + ", score " + hit.score());
+        }
+        //end::search-template-query
+    }
 }