diff --git a/docs/reference/aggregations/metrics.asciidoc b/docs/reference/aggregations/metrics.asciidoc index cbea8d82576d..5143afddf816 100644 --- 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 new file mode 100644 index 000000000000..0a560c9be562 --- /dev/null +++ b/docs/reference/aggregations/metrics/cartesian-bounds-aggregation.asciidoc @@ -0,0 +1,148 @@ +[[search-aggregations-metrics-cartesian-bounds-aggregation]] +=== Cartesian-bounds aggregation +++++ +Cartesian-bounds +++++ + +A metric aggregation that computes the spatial bounding box containing all values for a <> or <> 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 <> or a <> type. + +[NOTE] +Unlike the case with the <> aggregation, +there is no option to set <>. +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 index b6562f01842a..662b673fcd9a 100644 --- 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 <> or a <> type) +<1> The `cartesian_centroid` aggregation specifies the field to use for computing the centroid, which must be a <> or a <> 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 index 6b83f8654887..35ac798f364b 100644 --- a/docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc +++ b/docs/reference/aggregations/metrics/geobounds-aggregation.asciidoc @@ -4,7 +4,7 @@ Geo-bounds ++++ -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 <> or <> 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 <> or a <> 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 index 1d3d59b8dc31..39e8d52824bc 100644 --- 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: * <> * <> * <> +* <> * <> * <> * <>