Update Java documentation for 5.0

Some of the methods have been removed or deprecated. Also related to #21825. Backport of #21831 in 5.x branch.
elastic · Nov 30, 2016 · 32b05b9 · 32b05b9
1 parent 56faeb3
commit 32b05b9
Show file tree

Hide file tree

Showing 33 changed files with 189 additions and 210 deletions.
diff --git a/docs/java-api/aggregations/bucket/datehistogram-aggregation.asciidoc b/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));
 --------------------------------------------------
 
 

diff --git a/docs/java-api/aggregations/bucket/filters-aggregation.asciidoc b/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")), 
-            new KeyedFilter("women", QueryBuilders.termQuery("gender", "female")));
+        .filters("agg",
+            new FiltersAggregator.KeyedFilter("men", QueryBuilders.termQuery("gender", "male")),
+            new FiltersAggregator.KeyedFilter("women", QueryBuilders.termQuery("gender", "female")));
 --------------------------------------------------
 
 

diff --git a/docs/java-api/aggregations/bucket/histogram-aggregation.asciidoc b/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
+    Number key = (Number) entry.getKey();   // Key
     long docCount = entry.getDocCount();    // Doc count
 
     logger.info("key [{}], doc_count [{}]", key, docCount);

diff --git a/docs/java-api/aggregations/bucket/reverse-nested-aggregation.asciidoc b/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")

diff --git a/docs/java-api/aggregations/metrics/avg-aggregation.asciidoc b/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");

diff --git a/docs/java-api/aggregations/metrics/cardinality-aggregation.asciidoc b/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");

diff --git a/docs/java-api/aggregations/metrics/extendedstats-aggregation.asciidoc b/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");

diff --git a/docs/java-api/aggregations/metrics/geobounds-aggregation.asciidoc b/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);

diff --git a/docs/java-api/aggregations/metrics/max-aggregation.asciidoc b/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");

diff --git a/docs/java-api/aggregations/metrics/min-aggregation.asciidoc b/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");

diff --git a/docs/java-api/aggregations/metrics/percentile-aggregation.asciidoc b/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")

diff --git a/docs/java-api/aggregations/metrics/percentile-rank-aggregation.asciidoc b/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);
 --------------------------------------------------
 
 

diff --git a/docs/java-api/aggregations/metrics/scripted-metric-aggregation.asciidoc b/docs/java-api/aggregations/metrics/scripted-metric-aggregation.asciidoc
@@ -26,21 +26,20 @@ Here is an example on how to create the aggregation request:
 
 [source,java]
 --------------------------------------------------
-MetricsAggregationBuilder aggregation =
-        AggregationBuilders
-                .scriptedMetric("agg")
-                .initScript("_agg['heights'] = []")
-                .mapScript(new Script("if (doc['gender'].value == \"male\") " +
-                        "{ _agg.heights.add(doc['height'].value) } " +
-                        "else " +
-                        "{ _agg.heights.add(-1 * doc['height'].value) }"));
+ScriptedMetricAggregationBuilder aggregation = AggregationBuilders
+        .scriptedMetric("agg")
+        .initScript(new Script("_agg['heights'] = []"))
+        .mapScript(new Script("if (doc['gender'].value == \"male\") " +
+                "{ _agg.heights.add(doc['height'].value) } " +
+                "else " +
+                "{ _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'] = []"))
@@ -55,7 +54,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'] = []"))

diff --git a/docs/java-api/aggregations/metrics/stats-aggregation.asciidoc b/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");

diff --git a/docs/java-api/aggregations/metrics/sum-aggregation.asciidoc b/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");

diff --git a/docs/java-api/aggregations/metrics/valuecount-aggregation.asciidoc b/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");

diff --git a/docs/java-api/query-dsl/function-score-query.asciidoc b/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

diff --git a/docs/java-api/query-dsl/geo-distance-query.asciidoc b/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>
-    .optimizeBbox("memory")                         <4>
-    .geoDistance(GeoDistance.ARC);                  <5>
-
+    .distance(200, DistanceUnit.KILOMETERS);        <3>
 --------------------------------------------------
 <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)
 
diff --git a/docs/java-api/query-dsl/geo-distance-range-query.asciidoc b/docs/java-api/query-dsl/geo-distance-range-query.asciidoc
diff --git a/docs/java-api/query-dsl/geo-polygon-query.asciidoc b/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));

diff --git a/docs/java-api/query-dsl/geo-queries.asciidoc b/docs/java-api/query-dsl/geo-queries.asciidoc
@@ -21,11 +21,6 @@ The queries in this group are:
     Finds document with geo-points within the specified distance of a central
     point.
 
-<<java-query-dsl-geo-distance-range-query,`geo_distance_range`>> query::
-
-    Like the `geo_point` query, but the range starts at a specified distance
-    from the central point.
-
 <<java-query-dsl-geo-polygon-query,`geo_polygon`>> query::
 
     Find documents with geo-points within the specified polygon.
@@ -36,6 +31,4 @@ include::geo-bounding-box-query.asciidoc[]
 
 include::geo-distance-query.asciidoc[]
 
-include::geo-distance-range-query.asciidoc[]
-
 include::geo-polygon-query.asciidoc[]
diff --git a/docs/java-api/query-dsl/geo-shape-query.asciidoc b/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(
-        "pin.location",                 <1>
-        ShapeBuilder.newMultiPoint()    <2>
-             .point(0, 0)
-             .point(0, 10)
-             .point(10, 10)
-             .point(10, 0)
-             .point(0, 0));
-qb.relation(ShapeRelation.WITHIN);      <3>
+List<Coordinate> points = new ArrayList<>();
+points.add(new Coordinate(0, 0));
+points.add(new Coordinate(0, 10));
+points.add(new Coordinate(10, 10));
+points.add(new Coordinate(10, 0));
+points.add(new Coordinate(0, 0));
 
+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(
-        "pin.location",             <1>
-        "DEU",                      <2>
-        "countries");               <3>
-qb.relation(ShapeRelation.WITHIN))  <4>
-    .indexedShapeIndex("shapes")    <5>
-    .indexedShapePath("location");  <6>
+QueryBuilder qb = geoShapeQuery(
+        "pin.location",                  <1>
+        "DEU",                           <2>
+        "countries")                     <3>
+        .relation(ShapeRelation.WITHIN)) <4>
+        .indexedShapeIndex("shapes")     <5>
+        .indexedShapePath("location");   <6>
 --------------------------------------------------
 <1> field
 <2> The ID of the document that containing the pre-indexed shape.

diff --git a/docs/java-api/query-dsl/has-child-query.asciidoc b/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`
 
diff --git a/docs/java-api/query-dsl/has-parent-query.asciidoc b/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
diff --git a/docs/java-api/query-dsl/nested-query.asciidoc b/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))
-    )
-    .scoreMode(ScoreMode.Avg);        <3>
+                .must(rangeQuery("obj1.count").gt(5)),
+        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`
diff --git a/docs/java-api/query-dsl/script-query.asciidoc b/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>
-        ScriptType.FILE,       <2>
-        "painless",                          <3>
-        ImmutableMap.of("param1", 5))        <4>
+        "myscript",                            <1>
+        ScriptType.FILE,                       <2>
+        "painless",                            <3>
+        Collections.singletonMap("param1", 5)) <4>
 );
 --------------------------------------------------
 <1> Script name

diff --git a/docs/java-api/query-dsl/span-containing-query.asciidoc b/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>
 --------------------------------------------------