Aggregations: Adds GeoBounds Aggregation

The GeoBounds Aggregation is a new single bucket aggregation which outputs the coordinates of a bounding box containing all the points from all the documents passed to the aggregation as well as the doc count. Geobound Aggregation also use a wrap_logitude parameter which specifies whether the resulting bounding box is permitted to overlap the international date line.  This option defaults to true.

This aggregation introduces the idea of MetricsAggregation which do not return double values and cannot be used for sorting.  The existing MetricsAggregation has been renamed to NumericMetricsAggregation and is a subclass of MetricsAggregation.  MetricsAggregations do not store doc counts and do not support child aggregations.

Closes #5634

Author: colings86

docs/reference/search/aggregations.asciidoc

@@ -109,11 +109,13 @@ minimum value among all other values associated with the same document).
 
 The aggregations in this family compute metrics based on values extracted in one way or another from the documents that
 are being aggregated. The values are typically extracted from the fields of the document (using the field data), but
-can also be generated using scripts. Some aggregations output a single metric (e.g. `avg`) and are called `single-value
-metrics aggregation`, others generate multiple metrics (e.g. `stats`) and are called `multi-value metrics aggregation`.
-The distinction between single-value and multi-value metrics aggregations plays a role when these aggregations serve as
-direct sub-aggregations of some bucket aggregations (some bucket aggregation enable you to sort the returned buckets based
-on the metrics in each bucket).
+can also be generated using scripts. 
+
+Numeric metrics aggregations are a special type of metrics aggregation which output numeric values. Some aggregations output
+a single numeric metric (e.g. `avg`) and are called `single-value numeric metrics aggregation`, others generate multiple 
+metrics (e.g. `stats`) and are called `multi-value numeric metrics aggregation`. The distinction between single-value and 
+multi-value numeric metrics aggregations plays a role when these aggregations serve as direct sub-aggregations of some 
+bucket aggregations (some bucket aggregation enable you to sort the returned buckets based on the numeric metrics in each bucket).
 
 
 [float]

docs/reference/search/aggregations/metrics.asciidoc

@@ -17,3 +17,5 @@ include::metrics/valuecount-aggregation.asciidoc[]
 include::metrics/percentile-aggregation.asciidoc[]
 
 include::metrics/cardinality-aggregation.asciidoc[]
+
+include::metrics/geobounds-aggregation.asciidoc[]

docs/reference/search/aggregations/metrics/geobounds-aggregation.asciidoc

@@ -0,0 +1,61 @@
+[[search-aggregations-metrics-geobounds-aggregation]]
+=== Geo Bounds Aggregation
+
+coming[1.3.0]
+
+A metric aggregation that computes the bounding box containing all geo_point values for a field.
+
+.Experimental!
+[IMPORTANT]
+=====
+This feature is marked as experimental, and may be subject to change in the
+future.  If you use this feature, please let us know your experience with it!
+=====
+
+Example:
+
+[source,js]
+--------------------------------------------------
+{
+    "query" : {
+        "match" : { "business_type" : "shop" }
+    },
+    "aggs" : {
+        "viewport" : {
+            "geo_bounds" : {
+                "field" : "location" <1>
+                "wrap_longitude" : "true" <2>
+            }
+        }
+    }
+}
+--------------------------------------------------
+
+<1> The `geo_bounds` aggregation specifies the field to use to obtain the bounds
+<2> `wrap_longitude` is an optional parameter which specifies whether the bounding box should be allowed to overlap the international date line. The default value is `true`
+
+The above aggregation demonstrates how one would compute the bounding box of the location field for all documents with a business type of shop
+
+The response for the above aggregation:
+
+[source,js]
+--------------------------------------------------
+{
+    ...
+
+    "aggregations": {
+        "viewport": {
+            "bounds": {
+                "top_left": {
+                    "lat": 80.45,
+                    "lon": -160.22
+                },
+                "bottom_right": {
+                    "lat": 40.65,
+                    "lon": 42.57
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------

src/main/java/org/elasticsearch/index/query/functionscore/DecayFunctionParser.java

@@ -50,7 +50,7 @@
 import org.elasticsearch.index.query.functionscore.gauss.GaussDecayFunctionBuilder;
 import org.elasticsearch.index.query.functionscore.gauss.GaussDecayFunctionParser;
 import org.elasticsearch.search.MultiValueMode;
-import org.elasticsearch.search.aggregations.metrics.MetricsAggregation;
+import org.elasticsearch.search.aggregations.metrics.InternalNumericMetricsAggregation;
 import org.elasticsearch.search.internal.SearchContext;
 
 import java.io.IOException;

src/main/java/org/elasticsearch/search/aggregations/AggregationBuilders.java

@@ -25,16 +25,17 @@
 import org.elasticsearch.search.aggregations.bucket.histogram.HistogramBuilder;
 import org.elasticsearch.search.aggregations.bucket.missing.MissingBuilder;
 import org.elasticsearch.search.aggregations.bucket.nested.NestedBuilder;
+import org.elasticsearch.search.aggregations.bucket.nested.ReverseNestedBuilder;
 import org.elasticsearch.search.aggregations.bucket.range.RangeBuilder;
 import org.elasticsearch.search.aggregations.bucket.range.date.DateRangeBuilder;
 import org.elasticsearch.search.aggregations.bucket.range.geodistance.GeoDistanceBuilder;
 import org.elasticsearch.search.aggregations.bucket.range.ipv4.IPv4RangeBuilder;
-import org.elasticsearch.search.aggregations.bucket.nested.ReverseNestedBuilder;
 import org.elasticsearch.search.aggregations.bucket.significant.SignificantTermsBuilder;
 import org.elasticsearch.search.aggregations.bucket.terms.TermsBuilder;
 import org.elasticsearch.search.aggregations.bucket.tophits.TopHitsBuilder;
 import org.elasticsearch.search.aggregations.metrics.avg.AvgBuilder;
 import org.elasticsearch.search.aggregations.metrics.cardinality.CardinalityBuilder;
+import org.elasticsearch.search.aggregations.metrics.geobounds.GeoBoundsBuilder;
 import org.elasticsearch.search.aggregations.metrics.max.MaxBuilder;
 import org.elasticsearch.search.aggregations.metrics.min.MinBuilder;
 import org.elasticsearch.search.aggregations.metrics.percentiles.PercentilesBuilder;
@@ -146,4 +147,8 @@ public static CardinalityBuilder cardinality(String name) {
     public static TopHitsBuilder topHits(String name) {
         return new TopHitsBuilder(name);
     }
+    
+    public static GeoBoundsBuilder geoBounds(String name) {
+        return new GeoBoundsBuilder(name);
+    }
 }

src/main/java/org/elasticsearch/search/aggregations/AggregationModule.java

@@ -28,16 +28,17 @@
 import org.elasticsearch.search.aggregations.bucket.histogram.HistogramParser;
 import org.elasticsearch.search.aggregations.bucket.missing.MissingParser;
 import org.elasticsearch.search.aggregations.bucket.nested.NestedParser;
+import org.elasticsearch.search.aggregations.bucket.nested.ReverseNestedParser;
 import org.elasticsearch.search.aggregations.bucket.range.RangeParser;
 import org.elasticsearch.search.aggregations.bucket.range.date.DateRangeParser;
 import org.elasticsearch.search.aggregations.bucket.range.geodistance.GeoDistanceParser;
 import org.elasticsearch.search.aggregations.bucket.range.ipv4.IpRangeParser;
-import org.elasticsearch.search.aggregations.bucket.nested.ReverseNestedParser;
 import org.elasticsearch.search.aggregations.bucket.significant.SignificantTermsParser;
 import org.elasticsearch.search.aggregations.bucket.terms.TermsParser;
 import org.elasticsearch.search.aggregations.bucket.tophits.TopHitsParser;
 import org.elasticsearch.search.aggregations.metrics.avg.AvgParser;
 import org.elasticsearch.search.aggregations.metrics.cardinality.CardinalityParser;
+import org.elasticsearch.search.aggregations.metrics.geobounds.GeoBoundsParser;
 import org.elasticsearch.search.aggregations.metrics.max.MaxParser;
 import org.elasticsearch.search.aggregations.metrics.min.MinParser;
 import org.elasticsearch.search.aggregations.metrics.percentiles.PercentilesParser;
@@ -81,6 +82,7 @@ public AggregationModule() {
         parsers.add(NestedParser.class);
         parsers.add(ReverseNestedParser.class);
         parsers.add(TopHitsParser.class);
+        parsers.add(GeoBoundsParser.class);
     }
 
     /**

src/main/java/org/elasticsearch/search/aggregations/TransportAggregationModule.java

@@ -26,11 +26,11 @@
 import org.elasticsearch.search.aggregations.bucket.histogram.InternalHistogram;
 import org.elasticsearch.search.aggregations.bucket.missing.InternalMissing;
 import org.elasticsearch.search.aggregations.bucket.nested.InternalNested;
+import org.elasticsearch.search.aggregations.bucket.nested.InternalReverseNested;
 import org.elasticsearch.search.aggregations.bucket.range.InternalRange;
 import org.elasticsearch.search.aggregations.bucket.range.date.InternalDateRange;
 import org.elasticsearch.search.aggregations.bucket.range.geodistance.InternalGeoDistance;
 import org.elasticsearch.search.aggregations.bucket.range.ipv4.InternalIPv4Range;
-import org.elasticsearch.search.aggregations.bucket.nested.InternalReverseNested;
 import org.elasticsearch.search.aggregations.bucket.significant.SignificantLongTerms;
 import org.elasticsearch.search.aggregations.bucket.significant.SignificantStringTerms;
 import org.elasticsearch.search.aggregations.bucket.significant.UnmappedSignificantTerms;
@@ -41,6 +41,7 @@
 import org.elasticsearch.search.aggregations.bucket.tophits.InternalTopHits;
 import org.elasticsearch.search.aggregations.metrics.avg.InternalAvg;
 import org.elasticsearch.search.aggregations.metrics.cardinality.InternalCardinality;
+import org.elasticsearch.search.aggregations.metrics.geobounds.InternalGeoBounds;
 import org.elasticsearch.search.aggregations.metrics.max.InternalMax;
 import org.elasticsearch.search.aggregations.metrics.min.InternalMin;
 import org.elasticsearch.search.aggregations.metrics.percentiles.InternalPercentiles;
@@ -89,5 +90,6 @@ protected void configure() {
         InternalNested.registerStream();
         InternalReverseNested.registerStream();
         InternalTopHits.registerStreams();
+        InternalGeoBounds.registerStream();
     }
 }

src/main/java/org/elasticsearch/search/aggregations/bucket/terms/InternalOrder.java

@@ -28,7 +28,7 @@
 import org.elasticsearch.search.aggregations.bucket.BucketsAggregator;
 import org.elasticsearch.search.aggregations.bucket.MultiBucketsAggregation;
 import org.elasticsearch.search.aggregations.bucket.SingleBucketAggregator;
-import org.elasticsearch.search.aggregations.metrics.MetricsAggregator;
+import org.elasticsearch.search.aggregations.metrics.NumericMetricsAggregator;
 import org.elasticsearch.search.aggregations.support.OrderPath;
 
 import java.io.IOException;
@@ -171,13 +171,13 @@ public int compare(Terms.Bucket o1, Terms.Bucket o2) {
             // with only support single-bucket aggregators
             assert !(aggregator instanceof BucketsAggregator) : "this should be picked up before the aggregation is executed - on validate";
 
-            if (aggregator instanceof MetricsAggregator.MultiValue) {
+            if (aggregator instanceof NumericMetricsAggregator.MultiValue) {
                 assert key != null : "this should be picked up before the aggregation is executed - on validate";
                 return new Comparator<Terms.Bucket>() {
                     @Override
                     public int compare(Terms.Bucket o1, Terms.Bucket o2) {
-                        double v1 = ((MetricsAggregator.MultiValue) aggregator).metric(key, ((InternalTerms.Bucket) o1).bucketOrd);
-                        double v2 = ((MetricsAggregator.MultiValue) aggregator).metric(key, ((InternalTerms.Bucket) o2).bucketOrd);
+                        double v1 = ((NumericMetricsAggregator.MultiValue) aggregator).metric(key, ((InternalTerms.Bucket) o1).bucketOrd);
+                        double v2 = ((NumericMetricsAggregator.MultiValue) aggregator).metric(key, ((InternalTerms.Bucket) o2).bucketOrd);
                         // some metrics may return NaN (eg. avg, variance, etc...) in which case we'd like to push all of those to
                         // the bottom
                         return Comparators.compareDiscardNaN(v1, v2, asc);
@@ -189,8 +189,8 @@ public int compare(Terms.Bucket o1, Terms.Bucket o2) {
             return new Comparator<Terms.Bucket>() {
                 @Override
                 public int compare(Terms.Bucket o1, Terms.Bucket o2) {
-                    double v1 = ((MetricsAggregator.SingleValue) aggregator).metric(((InternalTerms.Bucket) o1).bucketOrd);
-                    double v2 = ((MetricsAggregator.SingleValue) aggregator).metric(((InternalTerms.Bucket) o2).bucketOrd);
+                    double v1 = ((NumericMetricsAggregator.SingleValue) aggregator).metric(((InternalTerms.Bucket) o1).bucketOrd);
+                    double v2 = ((NumericMetricsAggregator.SingleValue) aggregator).metric(((InternalTerms.Bucket) o2).bucketOrd);
                     // some metrics may return NaN (eg. avg, variance, etc...) in which case we'd like to push all of those to
                     // the bottom
                     return Comparators.compareDiscardNaN(v1, v2, asc);

src/main/java/org/elasticsearch/search/aggregations/metrics/InternalMetricsAggregation.java

@@ -0,0 +1,31 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.elasticsearch.search.aggregations.metrics;
+
+import org.elasticsearch.search.aggregations.InternalAggregation;
+
+public abstract class InternalMetricsAggregation extends InternalAggregation {
+
+    protected InternalMetricsAggregation() {} // for serialization
+
+    protected InternalMetricsAggregation(String name) {
+        super(name);
+    }
+}

src/main/java/org/elasticsearch/search/aggregations/metrics/MetricsAggregation.java renamed to src/main/java/org/elasticsearch/search/aggregations/metrics/InternalNumericMetricsAggregation.java

@@ -18,17 +18,16 @@
  */
 package org.elasticsearch.search.aggregations.metrics;
 
-import org.elasticsearch.search.aggregations.InternalAggregation;
 import org.elasticsearch.search.aggregations.support.format.ValueFormatter;
 
 /**
  *
  */
-public abstract class MetricsAggregation extends InternalAggregation {
+public abstract class InternalNumericMetricsAggregation extends InternalMetricsAggregation {
 
     protected ValueFormatter valueFormatter;
 
-    public static abstract class SingleValue extends MetricsAggregation {
+    public static abstract class SingleValue extends InternalNumericMetricsAggregation {
 
         protected SingleValue() {}
 
@@ -39,7 +38,7 @@ protected SingleValue(String name) {
         public abstract double value();
     }
 
-    public static abstract class MultiValue extends MetricsAggregation {
+    public static abstract class MultiValue extends InternalNumericMetricsAggregation {
 
         protected MultiValue() {}
 
@@ -51,9 +50,9 @@ protected MultiValue(String name) {
 
     }
 
-    protected MetricsAggregation() {} // for serialization
+    protected InternalNumericMetricsAggregation() {} // for serialization
 
-    protected MetricsAggregation(String name) {
+    protected InternalNumericMetricsAggregation(String name) {
         super(name);
     }
 

src/main/java/org/elasticsearch/search/aggregations/metrics/MetricsAggregator.java

@@ -16,38 +16,16 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+
 package org.elasticsearch.search.aggregations.metrics;
 
 import org.elasticsearch.search.aggregations.Aggregator;
 import org.elasticsearch.search.aggregations.AggregatorFactories;
 import org.elasticsearch.search.aggregations.support.AggregationContext;
 
-/**
- *
- */
 public abstract class MetricsAggregator extends Aggregator {
 
-    private MetricsAggregator(String name, long estimatedBucketsCount, AggregationContext context, Aggregator parent) {
+    protected MetricsAggregator(String name, long estimatedBucketsCount, AggregationContext context, Aggregator parent) {
         super(name, BucketAggregationMode.MULTI_BUCKETS, AggregatorFactories.EMPTY, estimatedBucketsCount, context, parent);
     }
-
-    public static abstract class SingleValue extends MetricsAggregator {
-
-        protected SingleValue(String name, long estimatedBucketsCount, AggregationContext context, Aggregator parent) {
-            super(name, estimatedBucketsCount, context, parent);
-        }
-
-        public abstract double metric(long owningBucketOrd);
-    }
-
-    public static abstract class MultiValue extends MetricsAggregator {
-
-        protected MultiValue(String name, long estimatedBucketsCount, AggregationContext context, Aggregator parent) {
-            super(name, estimatedBucketsCount, context, parent);
-        }
-
-        public abstract boolean hasMetric(String name);
-
-        public abstract double metric(String name, long owningBucketOrd);
-    }
 }

src/main/java/org/elasticsearch/search/aggregations/metrics/NumericMetricsAggregator.java

@@ -0,0 +1,52 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.search.aggregations.metrics;
+
+import org.elasticsearch.search.aggregations.Aggregator;
+import org.elasticsearch.search.aggregations.support.AggregationContext;
+
+/**
+ *
+ */
+public abstract class NumericMetricsAggregator extends MetricsAggregator {
+
+    private NumericMetricsAggregator(String name, long estimatedBucketsCount, AggregationContext context, Aggregator parent) {
+        super(name, estimatedBucketsCount, context, parent);
+    }
+
+    public static abstract class SingleValue extends NumericMetricsAggregator {
+
+        protected SingleValue(String name, long estimatedBucketsCount, AggregationContext context, Aggregator parent) {
+            super(name, estimatedBucketsCount, context, parent);
+        }
+
+        public abstract double metric(long owningBucketOrd);
+    }
+
+    public static abstract class MultiValue extends NumericMetricsAggregator {
+
+        protected MultiValue(String name, long estimatedBucketsCount, AggregationContext context, Aggregator parent) {
+            super(name, estimatedBucketsCount, context, parent);
+        }
+
+        public abstract boolean hasMetric(String name);
+
+        public abstract double metric(String name, long owningBucketOrd);
+    }
+}

src/main/java/org/elasticsearch/search/aggregations/metrics/NumericValuesSourceMetricsAggregatorParser.java

@@ -33,7 +33,7 @@
 /**
  *
  */
-public abstract class NumericValuesSourceMetricsAggregatorParser<S extends MetricsAggregation> implements Aggregator.Parser {
+public abstract class NumericValuesSourceMetricsAggregatorParser<S extends InternalNumericMetricsAggregation> implements Aggregator.Parser {
 
     protected final InternalAggregation.Type aggType;