add geo_shape documentation for supported aggregations (#58284) (#58354)

This commit adds documentation for geo_shape fields in aggregations

Closes #55495.

docs/reference/aggregations/bucket/geohashgrid-aggregation.asciidoc

@@ -268,6 +268,16 @@ Cell dimensions vary with latitude and so the table is for the worst-case scenar
 12::	3.7cm x 1.9cm
 
 
+[discrete]
+[role="xpack"]
+==== Aggregating `geo_shape` fields
+
+Aggregating on <<geo-shape>> fields works just as it does for points, except that a single
+shape can be counted for in multiple tiles. A shape will contribute to the count of matching values
+if any part of its shape intersects with that tile. Below is an image that demonstrates this
+
+
+image:images/spatial/geoshape_grid.png[]
 
 ==== Options
 

docs/reference/aggregations/bucket/geotilegrid-aggregation.asciidoc

@@ -219,6 +219,17 @@ POST /museums/_search?size=0
 --------------------------------------------------
 // TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
 
+[discrete]
+[role="xpack"]
+==== Aggregating `geo_shape` fields
+
+Aggregating on <<geo-shape>> fields works just as it does for points, except that a single
+shape can be counted for in multiple tiles. A shape will contribute to the count of matching values
+if any part of its shape intersects with that tile. Below is an image that demonstrates this
+
+
+image:images/spatial/geoshape_grid.png[]
+
 ==== Options
 
 [horizontal]

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

@@ -1,7 +1,7 @@
 [[search-aggregations-metrics-geobounds-aggregation]]
 === Geo Bounds Aggregation
 
-A metric aggregation that computes the bounding box containing all geo_point values for a field.
+A metric aggregation that computes the bounding box containing all geo values for a field.
 
 
 Example:
@@ -77,3 +77,65 @@ The response for the above aggregation:
 }
 --------------------------------------------------
 // TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
+
+[discrete]
+[role="xpack"]
+==== Geo Bounds Aggregation on `geo_shape` fields
+
+The Geo Bounds Aggregation is also supported on `geo_shape` fields.
+
+Example:
+
+[source,console]
+--------------------------------------------------
+PUT /places
+{
+    "mappings": {
+        "properties": {
+            "geometry": {
+                "type": "geo_shape"
+            }
+        }
+    }
+}
+
+POST /places/_bulk?refresh
+{"index":{"_id":1}}
+{"name": "NEMO Science Museum", "geometry": "POINT(4.912350 52.374081)" }
+{"index":{"_id":2}}
+{"name": "Sportpark De Weeren", "geometry": { "type": "Polygon", "coordinates": [ [ [ 4.965305328369141, 52.39347642069457 ], [ 4.966979026794433, 52.391721758934835 ], [ 4.969425201416015, 52.39238958618537 ], [ 4.967944622039794, 52.39420969150824 ], [ 4.965305328369141, 52.39347642069457 ] ] ] } }
+
+POST /places/_search?size=0
+{
+    "aggs" : {
+        "viewport" : {
+            "geo_bounds" : {
+                "field" : "geometry"
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TEST
+
+[source,console-result]
+--------------------------------------------------
+{
+    ...
+    "aggregations": {
+        "viewport": {
+            "bounds": {
+                "top_left": {
+                    "lat": 52.39420966710895,
+                    "lon": 4.912349972873926
+                },
+                "bottom_right": {
+                    "lat": 52.374080987647176,
+                    "lon": 4.969425117596984
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]

docs/reference/aggregations/metrics/geocentroid-aggregation.asciidoc

@@ -1,7 +1,7 @@
 [[search-aggregations-metrics-geocentroid-aggregation]]
 === Geo Centroid Aggregation
 
-A metric aggregation that computes the weighted https://en.wikipedia.org/wiki/Centroid[centroid] from all coordinate values for a <<geo-point>> field.
+A metric aggregation that computes the weighted https://en.wikipedia.org/wiki/Centroid[centroid] from all coordinate values for geo fields.
 
 Example:
 
@@ -144,6 +144,87 @@ The response for the above aggregation:
 --------------------------------------------------
 // TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
 
+
+[discrete]
+[role="xpack"]
+==== Geo Centroid Aggregation on `geo_shape` fields
+
+The centroid metric for geo-shapes is more nuanced than for points. The centroid of a specific aggregation bucket
+containing shapes is the centroid of the highest-dimensionality shape type in the bucket. For example, if a bucket contains
+shapes comprising of polygons and lines, then the lines do not contribute to the centroid metric. Each type of shape's
+centroid is calculated differently. Envelopes and circles ingested via the <<ingest-circle-processor>> are treated
+as polygons.
+
+|===
+|Geometry Type | Centroid Calculation
+
+|[Multi]Point
+|equally weighted average of all the coordinates
+
+|[Multi]LineString
+|a weighted average of all the centroids of each segment, where the weight of each segment is its length in degrees
+
+|[Multi]Polygon
+|a weighted average of all the centroids of all the triangles of a polygon where the triangles are formed by every two consecutive vertices and the starting-point.
+ holes have negative weights. weights represent the area of the triangle in deg^2 calculated
+
+|GeometryCollection
+|The centroid of all the underlying geometries with the highest dimension. If Polygons and Lines and/or Points, then lines and/or points are ignored.
+ If Lines and Points, then points are ignored
+|===
+
+Example:
+
+[source,console]
+--------------------------------------------------
+PUT /places
+{
+    "mappings": {
+        "properties": {
+            "geometry": {
+                "type": "geo_shape"
+            }
+        }
+    }
+}
+
+POST /places/_bulk?refresh
+{"index":{"_id":1}}
+{"name": "NEMO Science Museum", "geometry": "POINT(4.912350 52.374081)" }
+{"index":{"_id":2}}
+{"name": "Sportpark De Weeren", "geometry": { "type": "Polygon", "coordinates": [ [ [ 4.965305328369141, 52.39347642069457 ], [ 4.966979026794433, 52.391721758934835 ], [ 4.969425201416015, 52.39238958618537 ], [ 4.967944622039794, 52.39420969150824 ], [ 4.965305328369141, 52.39347642069457 ] ] ] } }
+
+POST /places/_search?size=0
+{
+    "aggs" : {
+        "centroid" : {
+            "geo_centroid" : {
+                "field" : "geometry"
+            }
+        }
+    }
+}
+--------------------------------------------------
+// TEST
+
+[source,console-result]
+--------------------------------------------------
+{
+    ...
+    "aggregations": {
+        "centroid": {
+            "location": {
+                "lat": 52.39296147599816,
+                "lon": 4.967404240742326
+            },
+            "count": 2
+        }
+    }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
+
+
 [WARNING]
 .Using `geo_centroid` as a sub-aggregation of `geohash_grid`
 ====