Update Java documentation for 5.0

Some of the methods have been removed or deprecated.

Also related to #21825.

docs/java-api/aggregations/bucket/datehistogram-aggregation.asciidoc

@@ -16,7 +16,7 @@ AggregationBuilder aggregation =
         AggregationBuilders
                 .dateHistogram("agg")
                 .field("dateOfBirth")
-                .interval(DateHistogramInterval.YEAR);
+                .dateHistogramInterval(DateHistogramInterval.YEAR);
 --------------------------------------------------
 
 Or if you want to set an interval of 10 days:
@@ -27,7 +27,7 @@ AggregationBuilder aggregation =
         AggregationBuilders
                 .dateHistogram("agg")
                 .field("dateOfBirth")
-                .interval(DateHistogramInterval.days(10));
+                .dateHistogramInterval(DateHistogramInterval.days(10));
 --------------------------------------------------
 
 

docs/java-api/aggregations/bucket/filters-aggregation.asciidoc

@@ -14,8 +14,9 @@ Here is an example on how to create the aggregation request:
 --------------------------------------------------
 AggregationBuilder aggregation =
     AggregationBuilders
-        .filters("agg", new KeyedFilter("men", QueryBuilders.termQuery("gender", "male")), 
+        .filters("agg",
-            new KeyedFilter("women", QueryBuilders.termQuery("gender", "female")));
+            new FiltersAggregator.KeyedFilter("men", QueryBuilders.termQuery("gender", "male")),
+            new FiltersAggregator.KeyedFilter("women", QueryBuilders.termQuery("gender", "female")));
 --------------------------------------------------
 
 

docs/java-api/aggregations/bucket/histogram-aggregation.asciidoc

@@ -36,7 +36,7 @@ Histogram agg = sr.getAggregations().get("agg");
 
 // For each entry
 for (Histogram.Bucket entry : agg.getBuckets()) {
-    Long key = (Long) entry.getKey();       // Key
+    Double key = (Double) entry.getKey();   // Key
     long docCount = entry.getDocCount();    // Doc count
 
     logger.info("key [{}], doc_count [{}]", key, docCount);

docs/java-api/aggregations/bucket/reverse-nested-aggregation.asciidoc

@@ -14,7 +14,7 @@ Here is an example on how to create the aggregation request:
 --------------------------------------------------
 AggregationBuilder aggregation =
     AggregationBuilders
-        .nested("agg").path("resellers")
+        .nested("agg", "resellers")
         .subAggregation(
                 AggregationBuilders
                         .terms("name").field("resellers.name")

docs/java-api/aggregations/metrics/avg-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+AvgAggregationBuilder aggregation =
         AggregationBuilders
                 .avg("agg")
                 .field("height");

docs/java-api/aggregations/metrics/cardinality-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+CardinalityAggregationBuilder aggregation =
         AggregationBuilders
                 .cardinality("agg")
                 .field("tags");

docs/java-api/aggregations/metrics/extendedstats-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+ExtendedStatsAggregationBuilder aggregation =
         AggregationBuilders
                 .extendedStats("agg")
                 .field("height");

docs/java-api/aggregations/metrics/geobounds-aggregation.asciidoc

@@ -13,7 +13,7 @@ Here is an example on how to create the aggregation request:
 [source,java]
 --------------------------------------------------
 GeoBoundsBuilder aggregation =
-        AggregationBuilders
+        GeoBoundsAggregationBuilder
                 .geoBounds("agg")
                 .field("address.location")
                 .wrapLongitude(true);

docs/java-api/aggregations/metrics/max-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+MaxAggregationBuilder aggregation =
         AggregationBuilders
                 .max("agg")
                 .field("height");

docs/java-api/aggregations/metrics/min-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+MinAggregationBuilder aggregation =
         AggregationBuilders
                 .min("agg")
                 .field("height");

docs/java-api/aggregations/metrics/percentile-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+PercentilesAggregationBuilder aggregation =
         AggregationBuilders
                 .percentiles("agg")
                 .field("height");
@@ -22,7 +22,7 @@ You can provide your own percentiles instead of using defaults:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+PercentilesAggregationBuilder aggregation =
         AggregationBuilders
                 .percentiles("agg")
                 .field("height")

docs/java-api/aggregations/metrics/percentile-rank-aggregation.asciidoc

@@ -12,11 +12,11 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+PercentileRanksAggregationBuilder aggregation =
         AggregationBuilders
                 .percentileRanks("agg")
                 .field("height")
-                .percentiles(1.24, 1.91, 2.22);
+                .values(1.24, 1.91, 2.22);
 --------------------------------------------------
 
 

docs/java-api/aggregations/metrics/scripted-metric-aggregation.asciidoc

@@ -11,21 +11,20 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+ScriptedMetricAggregationBuilder aggregation = AggregationBuilders
-        AggregationBuilders
+        .scriptedMetric("agg")
-                .scriptedMetric("agg")
+        .initScript(new Script("_agg['heights'] = []"))
-                .initScript("_agg['heights'] = []")
+        .mapScript(new Script("if (doc['gender'].value == \"male\") " +
-                .mapScript(new Script("if (doc['gender'].value == \"male\") " +
+                "{ _agg.heights.add(doc['height'].value) } " +
-                        "{ _agg.heights.add(doc['height'].value) } " +
+                "else " +
-                        "else " +
+                "{ _agg.heights.add(-1 * doc['height'].value) }"));
-                        "{ _agg.heights.add(-1 * doc['height'].value) }"));
 --------------------------------------------------
 
 You can also specify a `combine` script which will be executed on each shard:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+ScriptedMetricAggregationBuilder aggregation =
         AggregationBuilders
                 .scriptedMetric("agg")
                 .initScript(new Script("_agg['heights'] = []"))
@@ -40,7 +39,7 @@ You can also specify a `reduce` script which will be executed on the node which
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+ScriptedMetricAggregationBuilder aggregation =
         AggregationBuilders
                 .scriptedMetric("agg")
                 .initScript(new Script("_agg['heights'] = []"))

docs/java-api/aggregations/metrics/stats-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+StatsAggregationBuilder aggregation =
         AggregationBuilders
                 .stats("agg")
                 .field("height");

docs/java-api/aggregations/metrics/sum-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+SumAggregationBuilder aggregation =
         AggregationBuilders
                 .sum("agg")
                 .field("height");

docs/java-api/aggregations/metrics/valuecount-aggregation.asciidoc

@@ -12,7 +12,7 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
+ValueCountAggregationBuilder aggregation =
         AggregationBuilders
                 .count("agg")
                 .field("height");

docs/java-api/query-dsl/function-score-query.asciidoc

@@ -19,6 +19,7 @@ FilterFunctionBuilder[] functions = {
         new FunctionScoreQueryBuilder.FilterFunctionBuilder(
                 exponentialDecayFunction("age", 0L, 1L))      <3>
 };
+QueryBuilder qb = QueryBuilders.functionScoreQuery(functions);
 --------------------------------------------------
 <1> Add a first function based on a query
 <2> And randomize the score based on a given seed

docs/java-api/query-dsl/geo-distance-query.asciidoc

@@ -7,15 +7,9 @@ See {ref}/query-dsl-geo-distance-query.html[Geo Distance Query]
 --------------------------------------------------
 QueryBuilder qb = geoDistanceQuery("pin.location")  <1>
     .point(40, -70)                                 <2>
-    .distance(200, DistanceUnit.KILOMETERS)         <3>
+    .distance(200, DistanceUnit.KILOMETERS);        <3>
-    .optimizeBbox("memory")                         <4>
-    .geoDistance(GeoDistance.ARC);                  <5>
-
 --------------------------------------------------
 <1> field
 <2> center point
 <3> distance from center point
-<4> optimize bounding box: `memory`, `indexed` or `none`
-<5> distance computation mode: `GeoDistance.SLOPPY_ARC` (default), `GeoDistance.ARC` (slightly more precise but
-    significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)
 

docs/java-api/query-dsl/geo-distance-range-query.asciidoc

@@ -1,26 +0,0 @@
-[[java-query-dsl-geo-distance-range-query]]
-==== Geo Distance Range Query
-
-See {ref}/query-dsl-geo-distance-range-query.html[Geo Distance Range Query]
-
-[source,java]
---------------------------------------------------
-QueryBuilder qb = geoDistanceRangeQuery("pin.location",         <1>
-        new GeoPoint(40, -70))                                  <2>
-    .from("200km")                                              <3>
-    .to("400km")                                                <4>
-    .includeLower(true)                                         <5>
-    .includeUpper(false)                                        <6>
-    .optimizeBbox("memory")                                     <7>
-    .geoDistance(GeoDistance.ARC);                              <8>
---------------------------------------------------
-<1> field
-<2> center point
-<3> starting distance from center point
-<4> ending distance from center point
-<5> include lower value means that `from` is `gt` when `false` or `gte` when `true`
-<6> include upper value means that `to` is `lt` when `false` or `lte` when `true`
-<7> optimize bounding box: `memory`, `indexed` or `none`
-<8> distance computation mode: `GeoDistance.SLOPPY_ARC` (default), `GeoDistance.ARC` (slightly more precise but
-    significantly slower) or `GeoDistance.PLANE` (faster, but inaccurate on long distances and close to the poles)
-

docs/java-api/query-dsl/geo-polygon-query.asciidoc

@@ -5,7 +5,7 @@ See {ref}/query-dsl-geo-polygon-query.html[Geo Polygon Query]
 
 [source,java]
 --------------------------------------------------
-List<GeoPoint> points = new ArrayList<GeoPoint>();     <1>
+List<GeoPoint> points = new ArrayList<>();             <1>
 points.add(new GeoPoint(40, -70));
 points.add(new GeoPoint(30, -80));
 points.add(new GeoPoint(20, -90));

docs/java-api/query-dsl/geo-queries.asciidoc

@@ -36,6 +36,4 @@ include::geo-bounding-box-query.asciidoc[]
 
 include::geo-distance-query.asciidoc[]
 
-include::geo-distance-range-query.asciidoc[]
-
 include::geo-polygon-query.asciidoc[]

docs/java-api/query-dsl/geo-shape-query.asciidoc

@@ -39,31 +39,32 @@ import org.elasticsearch.common.geo.builders.ShapeBuilder;
 
 [source,java]
 --------------------------------------------------
-GeoShapeQueryBuilder qb = geoShapeQuery(
+List<Coordinate> points = new ArrayList<>();
-        "pin.location",                 <1>
+points.add(new Coordinate(0, 0));
-        ShapeBuilder.newMultiPoint()    <2>
+points.add(new Coordinate(0, 10));
-             .point(0, 0)
+points.add(new Coordinate(10, 10));
-             .point(0, 10)
+points.add(new Coordinate(10, 0));
-             .point(10, 10)
+points.add(new Coordinate(0, 0));
-             .point(10, 0)
-             .point(0, 0));
-qb.relation(ShapeRelation.WITHIN);      <3>
 
+QueryBuilder qb = geoShapeQuery(
+        "pin.location",                         <1>
+        ShapeBuilders.newMultiPoint(points)     <2>
+        .relation(ShapeRelation.WITHIN);        <3>
 --------------------------------------------------
 <1> field
 <2> shape
-<3> relation can be `ShapeRelation.WITHIN`, `ShapeRelation.INTERSECTS` or `ShapeRelation.DISJOINT`
+<3> relation can be `ShapeRelation.CONTAINS`, `ShapeRelation.WITHIN`, `ShapeRelation.INTERSECTS` or `ShapeRelation.DISJOINT`
 
 [source,java]
 --------------------------------------------------
 // Using pre-indexed shapes
-GeoShapeQueryBuilder qb = geoShapeQuery(
+QueryBuilder qb = geoShapeQuery(
-        "pin.location",             <1>
+        "pin.location",                  <1>
-        "DEU",                      <2>
+        "DEU",                           <2>
-        "countries");               <3>
+        "countries")                     <3>
-qb.relation(ShapeRelation.WITHIN))  <4>
+        .relation(ShapeRelation.WITHIN)) <4>
-    .indexedShapeIndex("shapes")    <5>
+        .indexedShapeIndex("shapes")     <5>
-    .indexedShapePath("location");  <6>
+        .indexedShapePath("location");   <6>
 --------------------------------------------------
 <1> field
 <2> The ID of the document that containing the pre-indexed shape.

docs/java-api/query-dsl/has-child-query.asciidoc

@@ -7,9 +7,11 @@ See {ref}/query-dsl-has-child-query.html[Has Child Query]
 --------------------------------------------------
 QueryBuilder qb = hasChildQuery(
     "blog_tag",                     <1>
-    termQuery("tag","something")    <2>
+    termQuery("tag","something"),   <2>
+    ScoreMode.Avg                   <3>
 );
 --------------------------------------------------
 <1> child type to query against
 <2> query
+<3> score mode can be `ScoreMode.Avg`, `ScoreMode.Max`, `ScoreMode.Min`, `ScoreMode.None` or `ScoreMode.Total`
 

docs/java-api/query-dsl/has-parent-query.asciidoc

@@ -7,8 +7,10 @@ See {ref}/query-dsl-has-parent-query.html[Has Parent]
 --------------------------------------------------
 QueryBuilder qb = hasParentQuery(
     "blog",                         <1>
-    termQuery("tag","something")    <2>
+    termQuery("tag","something"),   <2>
+    false                           <3>
 );
 --------------------------------------------------
 <1> parent type to query against
 <2> query
+<3> whether the score from the parent hit should propogate to the child hit

docs/java-api/query-dsl/nested-query.asciidoc

@@ -9,10 +9,10 @@ QueryBuilder qb = nestedQuery(
         "obj1",                       <1>
         boolQuery()                   <2>
                 .must(matchQuery("obj1.name", "blue"))
-                .must(rangeQuery("obj1.count").gt(5))
+                .must(rangeQuery("obj1.count").gt(5)),
-    )
+        ScoreMode.Avg                 <3>
-    .scoreMode(ScoreMode.Avg);        <3>
+    );
 --------------------------------------------------
 <1> path to nested document
 <2> your query. Any fields referenced inside the query must use the complete path (fully qualified).
-<3> score mode could be `max`, `total`, `avg` (default) or `none`
+<3> score mode could be `ScoreMode.Max`, `ScoreMode.Min`, `ScoreMode.Total`, `ScoreMode.Avg` or `ScoreMode.None`

docs/java-api/query-dsl/script-query.asciidoc

@@ -25,10 +25,10 @@ You can use it then with:
 --------------------------------------------------
 QueryBuilder qb = scriptQuery(
     new Script(
-        "myscript",                          <1>
+        "myscript",                            <1>
-        ScriptType.FILE,       <2>
+        ScriptType.FILE,                       <2>
-        "painless",                          <3>
+        "painless",                            <3>
-        ImmutableMap.of("param1", 5))        <4>
+        Collections.singletonMap("param1", 5)) <4>
 );
 --------------------------------------------------
 <1> Script name

docs/java-api/query-dsl/span-containing-query.asciidoc

@@ -7,7 +7,7 @@ See {ref}/query-dsl-span-containing-query.html[Span Containing Query]
 --------------------------------------------------
 QueryBuilder qb = spanContainingQuery(
     spanNearQuery(spanTermQuery("field1","bar"), 5) <1>
-          .clause(spanTermQuery("field1","baz"))
+          .addClause(spanTermQuery("field1","baz"))
           .inOrder(true),
     spanTermQuery("field1","foo"));                 <2>
 --------------------------------------------------

docs/java-api/query-dsl/span-near-query.asciidoc

@@ -8,13 +8,11 @@ See {ref}/query-dsl-span-near-query.html[Span Near Query]
 QueryBuilder qb = spanNearQuery(
     spanTermQuery("field","value1"),            <1>
     12)                                         <2>
-    .clause(spanTermQuery("field","value2"))    <1>
+    .addClause(spanTermQuery("field","value2")) <1>
-    .clause(spanTermQuery("field","value3"))    <1>
+    .addClause(spanTermQuery("field","value3")) <1>
-    .inOrder(false)                             <3>
+    .inOrder(false);                            <3>
-    .collectPayloads(false);                    <4>
 --------------------------------------------------
 <1> span term queries
 <2> slop factor: the maximum number of intervening unmatched positions
 <3> whether matches are required to be in-order
-<4> collect payloads or not
 

docs/java-api/query-dsl/span-or-query.asciidoc

@@ -6,9 +6,9 @@ See {ref}/query-dsl-span-or-query.html[Span Or Query]
 [source,java]
 --------------------------------------------------
 QueryBuilder qb = spanOrQuery(
-    spanTermQuery("field","value1"))            <1>
+    spanTermQuery("field","value1"))               <1>
-    .clause(spanTermQuery("field","value2"))    <1>
+    .addClause(spanTermQuery("field","value2"))    <1>
-    .clause(spanTermQuery("field","value3"));   <1>
+    .addClause(spanTermQuery("field","value3"));   <1>
 --------------------------------------------------
 <1> span term queries
 

docs/java-api/query-dsl/span-within-query.asciidoc

@@ -7,7 +7,7 @@ See {ref}/query-dsl-span-within-query.html[Span Within Query]
 --------------------------------------------------
 QueryBuilder qb = spanWithinQuery(
     spanNearQuery(spanTermQuery("field1", "bar"), 5) <1>
-        .clause(spanTermQuery("field1", "baz"))
+        .addClause(spanTermQuery("field1", "baz"))
         .inOrder(true),
     spanTermQuery("field1", "foo"));                 <2>
 --------------------------------------------------

docs/java-api/query-dsl/special-queries.asciidoc

@@ -26,8 +26,6 @@ This query finds percolator queries based on documents.
 
 include::mlt-query.asciidoc[]
 
-include::template-query.asciidoc[]
-
 include::script-query.asciidoc[]
 
 include::percolate-query.asciidoc[]

docs/java-api/query-dsl/template-query.asciidoc

@@ -1,89 +0,0 @@
-[[java-query-dsl-template-query]]
-==== Template Query
-
-See {ref}/search-template.html[Search Template] documentation
-
-In order to use the `template` query from the Java API
-the lang-mustache module dependency should be on the classpath and
-the transport client should be loaded with the lang-mustache plugin:
-
-[source,java]
---------------------------------------------------
-TransportClient transportClient = TransportClient.builder()
-        .settings(Settings.builder().put("node.name", "node"))
-        .addPlugin(MustachePlugin.class)
-        .build();
-transportClient.addTransportAddress(
-        new InetSocketTransportAddress(new InetSocketAddress(InetAddresses.forString("127.0.0.1"), 9300))
-);
---------------------------------------------------
-
-Define your template parameters as a `Map<String,Object>`:
-
-[source,java]
---------------------------------------------------
-Map<String, Object> template_params = new HashMap<>();
-template_params.put("param_gender", "male");
---------------------------------------------------
-
-You can use your stored search templates in `config/scripts`.
-For example, if you have a file named `config/scripts/template_gender.mustache` containing:
-
-[source,js]
---------------------------------------------------
-{
-    "template" : {
-        "query" : {
-            "match" : {
-                "gender" : "{{param_gender}}"
-            }
-        }
-    }
-}
---------------------------------------------------
-// NOTCONSOLE
-
-Define your template query:
-
-[source,java]
---------------------------------------------------
-QueryBuilder qb = new TemplateQueryBuilder(
-    "gender_template",                  <1>
-    ScriptService.ScriptType.FILE,      <2>
-    template_params);                   <3>
---------------------------------------------------
-<1> template name
-<2> template stored on disk in `gender_template.mustache`
-<3> parameters
-
-You can also store your template in the cluster state:
-
-[source,java]
---------------------------------------------------
-client.admin().cluster().preparePutStoredScript()
-    .setScriptLang("mustache")
-    .setId("template_gender")
-    .setSource(new BytesArray(
-        "{\n" +
-        "    \"template\" : {\n" +
-        "        \"query\" : {\n" +
-        "            \"match\" : {\n" +
-        "                \"gender\" : \"{{param_gender}}\"\n" +
-        "            }\n" +
-        "        }\n" +
-        "    }\n" +
-        "}")).get();
---------------------------------------------------
-
-To execute a stored templates, use `ScriptService.ScriptType.STORED`:
-
-[source,java]
---------------------------------------------------
-QueryBuilder qb = new TemplateQueryBuilder(
-    "gender_template",                  <1>
-    ScriptType.STORED,                  <2>
-    template_params);                   <3>
---------------------------------------------------
-<1> template name
-<2> template stored in the cluster state
-<3> parameters

docs/java-api/search.asciidoc

@@ -21,8 +21,7 @@ SearchResponse response = client.prepareSearch("index1", "index2")
         .setQuery(QueryBuilders.termQuery("multi", "test"))                 // Query
         .setPostFilter(QueryBuilders.rangeQuery("age").from(12).to(18))     // Filter
         .setFrom(0).setSize(60).setExplain(true)
-        .execute()
+        .get();
-        .actionGet();
 --------------------------------------------------
 
 Note that all parameters are optional. Here is the smallest search call
@@ -31,7 +30,7 @@ you can write:
 [source,java]
 --------------------------------------------------
 // MatchAll on the whole cluster with all default options
-SearchResponse response = client.prepareSearch().execute().actionGet();
+SearchResponse response = client.prepareSearch().get();
 --------------------------------------------------
 
 NOTE:   Although the Java API defines the additional search types QUERY_AND_FETCH and
@@ -58,7 +57,7 @@ SearchResponse scrollResp = client.prepareSearch(test)
         .addSort(FieldSortBuilder.DOC_FIELD_NAME, SortOrder.ASC)
         .setScroll(new TimeValue(60000))
         .setQuery(qb)
-        .setSize(100).execute().actionGet(); //max of 100 hits will be returned for each scroll
+        .setSize(100).get(); //max of 100 hits will be returned for each scroll
 //Scroll until no hits are returned
 do {
     for (SearchHit hit : scrollResp.getHits().getHits()) {
@@ -85,7 +84,7 @@ SearchRequestBuilder srb2 = client
 MultiSearchResponse sr = client.prepareMultiSearch()
         .add(srb1)
         .add(srb2)
-        .execute().actionGet();
+        .get();
 
 // You will get all individual responses from MultiSearchResponse#getResponses()
 long nbHits = 0;
@@ -113,7 +112,7 @@ SearchResponse sr = client.prepareSearch()
                     .field("birth")
                     .dateHistogramInterval(DateHistogramInterval.YEAR)
     )
-    .execute().actionGet();
+    .get();
 
 // Get your facet results
 Terms agg1 = sr.getAggregations().get("agg1");
@@ -142,3 +141,115 @@ if (sr.isTerminatedEarly()) {
 }
 --------------------------------------------------
 <1> Finish after 1000 docs
+
+[[java-search-template]]
+==== Search Template
+
+See {ref}/search-template.html[Search Template] documentation
+
+Define your template parameters as a `Map<String,Object>`:
+
+[source,java]
+--------------------------------------------------
+Map<String, Object> template_params = new HashMap<>();
+template_params.put("param_gender", "male");
+--------------------------------------------------
+
+You can use your stored search templates in `config/scripts`.
+For example, if you have a file named `config/scripts/template_gender.mustache` containing:
+
+[source,js]
+--------------------------------------------------
+{
+    "template" : {
+        "query" : {
+            "match" : {
+                "gender" : "{{param_gender}}"
+            }
+        }
+    }
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+Create your search template request:
+
+[source,java]
+--------------------------------------------------
+SearchResponse sr = new SearchTemplateRequestBuilder(client)
+    .setScript("template_gender")                 <1>
+    .setScriptType(ScriptService.ScriptType.FILE) <2>
+    .setScriptParams(template_params)             <3>
+    .setRequest(new SearchRequest())              <4>
+    .get()                                        <5>
+    .getResponse();                               <6>
+--------------------------------------------------
+<1> template name
+<2> template stored on disk in `gender_template.mustache`
+<3> parameters
+<4> set the execution context (ie. define the index name here)
+<5> execute and get the template response
+<6> get from the template response the search response itself
+
+You can also store your template in the cluster state:
+
+[source,java]
+--------------------------------------------------
+client.admin().cluster().preparePutStoredScript()
+    .setScriptLang("mustache")
+    .setId("template_gender")
+    .setSource(new BytesArray(
+        "{\n" +
+        "    \"template\" : {\n" +
+        "        \"query\" : {\n" +
+        "            \"match\" : {\n" +
+        "                \"gender\" : \"{{param_gender}}\"\n" +
+        "            }\n" +
+        "        }\n" +
+        "    }\n" +
+        "}")).get();
+--------------------------------------------------
+
+To execute a stored templates, use `ScriptService.ScriptType.STORED`:
+
+[source,java]
+--------------------------------------------------
+SearchResponse sr = new SearchTemplateRequestBuilder(client)
+        .setScript("template_gender")                       <1>
+        .setScriptType(ScriptService.ScriptType.STORED)     <2>
+        .setScriptParams(template_params)                   <3>
+        .setRequest(new SearchRequest())                    <4>
+        .get()                                              <5>
+        .getResponse();                                     <6>
+--------------------------------------------------
+<1> template name
+<2> template stored in the cluster state
+<3> parameters
+<4> set the execution context (ie. define the index name here)
+<5> execute and get the template response
+<6> get from the template response the search response itself
+
+You can also execute inline templates:
+
+[source,java]
+--------------------------------------------------
+sr = new SearchTemplateRequestBuilder(client)
+        .setScript("{\n" +                                  <1>
+                "        \"query\" : {\n" +
+                "            \"match\" : {\n" +
+                "                \"gender\" : \"{{param_gender}}\"\n" +
+                "            }\n" +
+                "        }\n" +
+                "}")
+        .setScriptType(ScriptService.ScriptType.INLINE)    <2>
+        .setScriptParams(template_params)                  <3>
+        .setRequest(new SearchRequest())                   <4>
+        .get()                                             <5>
+        .getResponse();                                    <6>
+--------------------------------------------------
+<1> template name
+<2> template is passed inline
+<3> parameters
+<4> set the execution context (ie. define the index name here)
+<5> execute and get the template response
+<6> get from the template response the search response itself