Added documentation for cartesian-bounds aggregation (elastic#91623)

* Added documentation for cartesian-bounds aggregation * Fixed rounding errors in docs tests
craigtaverner · Nov 18, 2022 · a66d1be · a66d1be
1 parent e7011ef
commit a66d1be
Show file tree

Hide file tree

Showing 5 changed files with 163 additions and 13 deletions.
diff --git a/docs/reference/aggregations/metrics.asciidoc b/docs/reference/aggregations/metrics.asciidoc
@@ -25,6 +25,8 @@ include::metrics/geocentroid-aggregation.asciidoc[]
 
 include::metrics/geoline-aggregation.asciidoc[]
 
+include::metrics/cartesian-bounds-aggregation.asciidoc[]
+
 include::metrics/cartesian-centroid-aggregation.asciidoc[]
 
 include::metrics/matrix-stats-aggregation.asciidoc[]

diff --git a/docs/reference/aggregations/metrics/cartesian-bounds-aggregation.asciidoc b/docs/reference/aggregations/metrics/cartesian-bounds-aggregation.asciidoc
@@ -0,0 +1,148 @@
+[[search-aggregations-metrics-cartesian-bounds-aggregation]]
+=== Cartesian-bounds aggregation
+++++
+<titleabbrev>Cartesian-bounds</titleabbrev>
+++++
+
+A metric aggregation that computes the spatial bounding box containing all values for a <<point>> or <<shape>> field.
+
+Example:
+
+[source,console]
+--------------------------------------------------
+PUT /museums
+{
+  "mappings": {
+    "properties": {
+      "location": {
+        "type": "point"
+      }
+    }
+  }
+}
+
+POST /museums/_bulk?refresh
+{"index":{"_id":1}}
+{"location": "POINT (491.2350 5237.4081)", "city": "Amsterdam", "name": "NEMO Science Museum"}
+{"index":{"_id":2}}
+{"location": "POINT (490.1618 5236.9219)", "city": "Amsterdam", "name": "Museum Het Rembrandthuis"}
+{"index":{"_id":3}}
+{"location": "POINT (491.4722 5237.1667)", "city": "Amsterdam", "name": "Nederlands Scheepvaartmuseum"}
+{"index":{"_id":4}}
+{"location": "POINT (440.5200 5122.2900)", "city": "Antwerp", "name": "Letterenhuis"}
+{"index":{"_id":5}}
+{"location": "POINT (233.6389 4886.1111)", "city": "Paris", "name": "Musée du Louvre"}
+{"index":{"_id":6}}
+{"location": "POINT (232.7000 4886.0000)", "city": "Paris", "name": "Musée d'Orsay"}
+
+POST /museums/_search?size=0
+{
+  "query": {
+    "match": { "name": "musée" }
+  },
+  "aggs": {
+    "viewport": {
+      "cartesian_bounds": {
+        "field": "location"    <1>
+      }
+    }
+  }
+}
+--------------------------------------------------
+
+<1> The `cartesian_bounds` aggregation specifies the field to use to obtain the bounds, which must be a <<point>> or a <<shape>> type.
+
+[NOTE]
+Unlike the case with the <<geobounds-aggregation-geo-shape, `geo_bounds`>> aggregation,
+there is no option to set <<geo-bounds-wrap-longitude, `wrap_longitude`>>.
+This is because the cartesian space is euclidean and does not wrap back on itself.
+So the bounds will always have a minimum x value less than or equal to the maximum x value.
+
+The above aggregation demonstrates how one would compute the bounding box of the location field for all documents with a name matching "musée".
+
+The response for the above aggregation:
+
+[source,console-result]
+--------------------------------------------------
+{
+  ...
+  "aggregations": {
+    "viewport": {
+      "bounds": {
+        "top_left": {
+          "x": 232.6999969482422,
+          "y": 4886.111328125
+        },
+        "bottom_right": {
+          "x": 233.63890075683594,
+          "y": 4886.0
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
+
+[discrete]
+[role="xpack"]
+[[cartesian-bounds-aggregation-shape]]
+==== Cartesian Bounds Aggregation on `shape` fields
+
+The Cartesian Bounds Aggregation is also supported on `cartesian_shape` fields.
+
+Example:
+
+[source,console]
+--------------------------------------------------
+PUT /places
+{
+  "mappings": {
+    "properties": {
+      "geometry": {
+        "type": "shape"
+      }
+    }
+  }
+}
+
+POST /places/_bulk?refresh
+{"index":{"_id":1}}
+{"name": "NEMO Science Museum", "geometry": "POINT(491.2350 5237.4081)" }
+{"index":{"_id":2}}
+{"name": "Sportpark De Weeren", "geometry": { "type": "Polygon", "coordinates": [ [ [ 496.5305328369141, 5239.347642069457 ], [ 496.6979026794433, 5239.1721758934835 ], [ 496.9425201416015, 5239.238958618537 ], [ 496.7944622039794, 5239.420969150824 ], [ 496.5305328369141, 5239.347642069457 ] ] ] } }
+
+POST /places/_search?size=0
+{
+  "aggs": {
+    "viewport": {
+      "cartesian_bounds": {
+        "field": "geometry"
+      }
+    }
+  }
+}
+--------------------------------------------------
+// TEST
+
+[source,console-result]
+--------------------------------------------------
+{
+  ...
+  "aggregations": {
+    "viewport": {
+      "bounds": {
+        "top_left": {
+          "x": 491.2349853515625,
+          "y": 5239.4208984375
+        },
+        "bottom_right": {
+          "x": 496.9425048828125,
+          "y": 5237.408203125
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// TESTRESPONSE[s/\.\.\./"took": $body.took,"_shards": $body._shards,"hits":$body.hits,"timed_out":false,/]
diff --git a/docs/reference/aggregations/metrics/cartesian-centroid-aggregation.asciidoc b/docs/reference/aggregations/metrics/cartesian-centroid-aggregation.asciidoc
@@ -48,8 +48,7 @@ POST /museums/_search?size=0
 }
 --------------------------------------------------
 
-<1> The `cartesian_centroid` aggregation specifies the field to use for computing the centroid.
-(NOTE: field must be a <<point>> or a <<shape>> type)
+<1> The `cartesian_centroid` aggregation specifies the field to use for computing the centroid, which must be a <<point>> or a <<shape>> type.
 
 The above aggregation demonstrates how one would compute the centroid of the location field for all museums' documents.
 

diff --git a/docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc b/docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc
@@ -4,7 +4,7 @@
 <titleabbrev>Geo-bounds</titleabbrev>
 ++++
 
-A metric aggregation that computes the bounding box containing all geo values for a field.
+A metric aggregation that computes the geographic bounding box containing all values for a <<geo-point>> or <<geo-shape>> field.
 
 Example:
 
@@ -51,10 +51,10 @@ POST /museums/_search?size=0
 }
 --------------------------------------------------
 
-<1> The `geo_bounds` aggregation specifies the field to use to obtain the bounds.
+<1> The `geo_bounds` aggregation specifies the field to use to obtain the bounds, which must be a <<geo-point>> or a <<geo-shape>> type.
 <2> [[geo-bounds-wrap-longitude]] `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 above aggregation demonstrates how one would compute the bounding box of the location field for all documents with a name matching "musée".
 
 The response for the above aggregation:
 

diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc
@@ -558,26 +558,26 @@ The name of the vector field to search against. Must be a
 end::knn-field[]
 
 tag::knn-filter[]
-Query to filter the documents that can match. The kNN search will return the top 
-`k` documents that also match this filter. The value can be a single query or a 
-list of queries. If `filter` is not provided, all documents are allowed to 
+Query to filter the documents that can match. The kNN search will return the top
+`k` documents that also match this filter. The value can be a single query or a
+list of queries. If `filter` is not provided, all documents are allowed to
 match.
 end::knn-filter[]
 
 tag::knn-k[]
-Number of nearest neighbors to return as top hits. This value must be less than 
+Number of nearest neighbors to return as top hits. This value must be less than
 `num_candidates`.
 end::knn-k[]
 
 tag::knn-num-candidates[]
-The number of nearest neighbor candidates to consider per shard. Cannot exceed 
-10,000. {es} collects `num_candidates` results from each shard, then merges them 
-to find the top `k` results. Increasing `num_candidates` tends to improve the 
+The number of nearest neighbor candidates to consider per shard. Cannot exceed
+10,000. {es} collects `num_candidates` results from each shard, then merges them
+to find the top `k` results. Increasing `num_candidates` tends to improve the
 accuracy of the final `k` results.
 end::knn-num-candidates[]
 
 tag::knn-query-vector[]
-Query vector. Must have the same number of dimensions as the vector field you 
+Query vector. Must have the same number of dimensions as the vector field you
 are searching against.
 end::knn-query-vector[]
 
@@ -739,6 +739,7 @@ currently supported:
 * <<search-aggregations-metrics-geobounds-aggregation,Geo bounds>>
 * <<search-aggregations-metrics-geocentroid-aggregation,Geo centroid>>
 * <<search-aggregations-metrics-geo-line,Geo line>>
+* <<search-aggregations-metrics-cartesian-bounds-aggregation,Cartesian bounds>>
 * <<search-aggregations-metrics-cartesian-centroid-aggregation,Cartesian centroid>>
 * <<search-aggregations-metrics-max-aggregation,Max>>
 * <<search-aggregations-metrics-median-absolute-deviation-aggregation,Median absolute deviation>>