From 84ee2895b3b68918c970706798bdb7117564c8b1 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Fri, 28 Oct 2022 18:24:44 -0400 Subject: [PATCH 1/5] Adds GeoHex grid documentation Signed-off-by: Fanit Kolchina --- _opensearch/bucket-agg.md | 2 +- _opensearch/geohexgrid-agg.md | 317 ++++++++++++++++++++++++++++++++++ _opensearch/metric-agg.md | 2 +- _opensearch/pipeline-agg.md | 2 +- 4 files changed, 320 insertions(+), 3 deletions(-) create mode 100644 _opensearch/geohexgrid-agg.md diff --git a/_opensearch/bucket-agg.md b/_opensearch/bucket-agg.md index 5714f7f48d..03b047ad91 100644 --- a/_opensearch/bucket-agg.md +++ b/_opensearch/bucket-agg.md @@ -1,6 +1,6 @@ --- layout: default -title: Bucket Aggregations +title: Bucket aggregations parent: Aggregations nav_order: 2 has_children: false diff --git a/_opensearch/geohexgrid-agg.md b/_opensearch/geohexgrid-agg.md new file mode 100644 index 0000000000..46b469c3c5 --- /dev/null +++ b/_opensearch/geohexgrid-agg.md @@ -0,0 +1,317 @@ +--- +layout: default +title: GeoHex grid aggregations +parent: Aggregations +nav_order: 4 +has_children: false +--- + +# GeoHex grid aggregations + +The Hexagonal hierarchical geospatial indexing system (H3) partitions the Earth's areas into identifiable hexagon-shaped cells. + +The H3 grid system works well for proximity applications, because it overcomes the shortcomings of geohash's non-uniform partitions. Geohash encodes latitude and longitude pairs, leading to significantly smaller partitions near the poles and a degree of longitude near the equator. However, the H3 grid system's distortions are low and limited to five partitions of 122. These five partitions are placed in low-use areas (for example, in the middle of the ocean), leaving the essential areas error-free. Thus, grouping documents based on the H3 grid system provides a better aggregation than the geohash grid. + +The GeoHex grid aggregation groups [geopoints]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) into grid cells for geographical analysis. Each grid cell corresponds to an [H3 cell](https://h3geo.org/docs/core-library/h3Indexing/#h3-cell-indexp) and is identified using the [H3Index representation](https://h3geo.org/docs/core-library/h3Indexing/#h3index-representation). + +## Precision + +The `precision` parameter controls the level of granularity that determines the grid cell size. The lower the precision, the larger the grid cells. + +The following example illustrates low-precision and high-precision aggregation requests. + +To start, create an index and map the `location` field as geopoint: + +```json +PUT testindex +{ + "mappings": { + "properties": { + "location": { + "type": "geo_point" + } + } + } +} +``` + +Index the following documents into the sample index: + +```json +PUT testindex/_doc/1 +{ + "name": "Yellowstone National Park", + "location": "44.42, -110.59" +} + +PUT testindex/_doc/2 +{ + "name": "Yosemite National Park", + "location": "37.87, -119.53" +} + +PUT testindex/_doc/3 +{ + "name": "Death Valley National Park", + "location": "36.53, -116.93" +} +``` + +You can index geopoints in several formats. For a list of all supported formats, see the [geopoint documentation]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/). +{: .note} + +## Low-precision requests + +Run a low-precision request that should bucket all three documents together: + +```json +GET testindex/_search +{ + "aggregations": { + "grouped": { + "geohex_grid": { + "field": "location", + "precision": 1 + } + } + } +} +``` + +You can use either `GET` or `POST` HTTP method for GeoHex grid aggregation queries. +{: .note} + +The response groups documents 2 and 3 together because they are close enough to be bucketed in one grid cell: + +```json +{ + "took" : 4, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 3, + "relation" : "eq" + }, + "max_score" : 1.0, + "hits" : [ + { + "_index" : "testindex", + "_id" : "1", + "_score" : 1.0, + "_source" : { + "name" : "Yellowstone National Park", + "location" : "44.42, -110.59" + } + }, + { + "_index" : "testindex", + "_id" : "2", + "_score" : 1.0, + "_source" : { + "name" : "Yosemite National Park", + "location" : "37.87, -119.53" + } + }, + { + "_index" : "testindex", + "_id" : "3", + "_score" : 1.0, + "_source" : { + "name" : "Death Valley National Park", + "location" : "36.53, -116.93" + } + } + ] + }, + "aggregations" : { + "grouped" : { + "buckets" : [ + { + "key" : "8129bffffffffff", + "doc_count" : 2 + }, + { + "key" : "8128bffffffffff", + "doc_count" : 1 + } + ] + } + } +} +``` + +## High-precision requests + +Now run a higher precision request: + +```json +GET testindex/_search +{ + "aggregations": { + "grouped": { + "geohex_grid": { + "field": "location", + "precision": 6 + } + } + } +} +``` + +All three documents are bucketed separately because of higher granularity: + +```json +{ + "took" : 5, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 3, + "relation" : "eq" + }, + "max_score" : 1.0, + "hits" : [ + { + "_index" : "testindex", + "_id" : "1", + "_score" : 1.0, + "_source" : { + "name" : "Yellowstone National Park", + "location" : "44.42, -110.59" + } + }, + { + "_index" : "testindex", + "_id" : "2", + "_score" : 1.0, + "_source" : { + "name" : "Yosemite National Park", + "location" : "37.87, -119.53" + } + }, + { + "_index" : "testindex", + "_id" : "3", + "_score" : 1.0, + "_source" : { + "name" : "Death Valley National Park", + "location" : "36.53, -116.93" + } + } + ] + }, + "aggregations" : { + "grouped" : { + "buckets" : [ + { + "key" : "8629ab6dfffffff", + "doc_count" : 1 + }, + { + "key" : "8629857a7ffffff", + "doc_count" : 1 + }, + { + "key" : "862896017ffffff", + "doc_count" : 1 + } + ] + } + } +} +``` + +## Filtering requests + +High-precision requests are resource-intensive, so we recommend to use a filter like `geo_bounding_box` to limit the geographical area. For example, the following query applies a filter to limit the search area: + +```json +GET testindex1/_search +{ + "size" : 0, + "aggregations": { + "filtered": { + "filter": { + "geo_bounding_box": { + "location": { + "top_left": "38, -120", + "bottom_right": "36, -116" + } + } + }, + "aggregations": { + "grouped": { + "geohex_grid": { + "field": "location", + "precision": 6 + } + } + } + } + } +} +``` + +The response contains the two documents that are within the `geo_bounding_box` bounds: + +```json +{ + "took" : 4, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 3, + "relation" : "eq" + }, + "max_score" : null, + "hits" : [ ] + }, + "aggregations" : { + "filtered" : { + "doc_count" : 2, + "grouped" : { + "buckets" : [ + { + "key" : "8629ab6dfffffff", + "doc_count" : 1 + }, + { + "key" : "8629857a7ffffff", + "doc_count" : 1 + } + ] + } + } + } +} +``` + +## Supported parameters + +GeoHex grid aggregation requests support the following parameters. + +Field | Data Type | Description +:--- | :--- | :--- +field | String | The field that contains the geopoints. This field must be mapped as a `geo_point` field. If the field contains an array, all array values are aggregated. Required. +precision | Integer | The zoom level used to determine grid cells for bucketing results. Valid values are in the [0, 15] range. Default is 5. +bounds | Object | The bounding box for filtering geopoints. The bounding box is defined by the top left and bottom right vertices. The vertices are specified as geopoints in one of the following formats:
- An object with a latitude and longitude
- An array in the [`longitude`, `latitude`] format
- A string in the "`latitude`,`longitude`" format
- A geohash
- Well-known text (WKT).
See the [geopoint documentation]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) for format examples. Optional. +size | Integer | The maximum number of buckets to return. When there are more buckets than `size`, OpenSearch returns buckets with more documents. Optional. Default is 10,000. +shard_size | Integer | The maximum number of buckets to return from each shard. Optional. Default is max (10, `size` · number of shards), which gives a more accurate count of higher prioritized buckets. \ No newline at end of file diff --git a/_opensearch/metric-agg.md b/_opensearch/metric-agg.md index 9211aacc5c..4418537b78 100644 --- a/_opensearch/metric-agg.md +++ b/_opensearch/metric-agg.md @@ -1,6 +1,6 @@ --- layout: default -title: Metric Aggregations +title: Metric aggregations parent: Aggregations nav_order: 1 has_children: false diff --git a/_opensearch/pipeline-agg.md b/_opensearch/pipeline-agg.md index 5e735f2cff..2a783c9954 100644 --- a/_opensearch/pipeline-agg.md +++ b/_opensearch/pipeline-agg.md @@ -1,6 +1,6 @@ --- layout: default -title: Pipeline Aggregations +title: Pipeline aggregations parent: Aggregations nav_order: 4 has_children: false From d7917c351b8aee9fb8aa6eb5d8494253f2f9bccb Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Fri, 28 Oct 2022 18:44:19 -0400 Subject: [PATCH 2/5] Renamed field Signed-off-by: Fanit Kolchina --- _opensearch/geohexgrid-agg.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/geohexgrid-agg.md b/_opensearch/geohexgrid-agg.md index 46b469c3c5..8787f6abb1 100644 --- a/_opensearch/geohexgrid-agg.md +++ b/_opensearch/geohexgrid-agg.md @@ -308,7 +308,7 @@ The response contains the two documents that are within the `geo_bounding_box` b GeoHex grid aggregation requests support the following parameters. -Field | Data Type | Description +Parameter | Data Type | Description :--- | :--- | :--- field | String | The field that contains the geopoints. This field must be mapped as a `geo_point` field. If the field contains an array, all array values are aggregated. Required. precision | Integer | The zoom level used to determine grid cells for bucketing results. Valid values are in the [0, 15] range. Default is 5. From 16e84e4d8bd89d7352530fc4c34900387aae6ace Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Tue, 1 Nov 2022 21:55:20 -0400 Subject: [PATCH 3/5] Added bounds parameter Signed-off-by: Fanit Kolchina --- _opensearch/geohexgrid-agg.md | 92 +++++++++++++++++++++++++++++------ 1 file changed, 76 insertions(+), 16 deletions(-) diff --git a/_opensearch/geohexgrid-agg.md b/_opensearch/geohexgrid-agg.md index 8787f6abb1..55e7c9197f 100644 --- a/_opensearch/geohexgrid-agg.md +++ b/_opensearch/geohexgrid-agg.md @@ -20,10 +20,10 @@ The `precision` parameter controls the level of granularity that determines the The following example illustrates low-precision and high-precision aggregation requests. -To start, create an index and map the `location` field as geopoint: +To start, create an index and map the `location` field as a `geo_point`: ```json -PUT testindex +PUT national_parks { "mappings": { "properties": { @@ -38,26 +38,26 @@ PUT testindex Index the following documents into the sample index: ```json -PUT testindex/_doc/1 +PUT national_parks/_doc/1 { "name": "Yellowstone National Park", "location": "44.42, -110.59" } -PUT testindex/_doc/2 +PUT national_parks/_doc/2 { "name": "Yosemite National Park", "location": "37.87, -119.53" } -PUT testindex/_doc/3 +PUT national_parks/_doc/3 { "name": "Death Valley National Park", "location": "36.53, -116.93" } ``` -You can index geopoints in several formats. For a list of all supported formats, see the [geopoint documentation]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/). +You can index geopoints in several formats. For a list of all supported formats, see the [geopoint documentation]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats). {: .note} ## Low-precision requests @@ -65,7 +65,7 @@ You can index geopoints in several formats. For a list of all supported formats, Run a low-precision request that should bucket all three documents together: ```json -GET testindex/_search +GET national_parks/_search { "aggregations": { "grouped": { @@ -101,7 +101,7 @@ The response groups documents 2 and 3 together because they are close enough to "max_score" : 1.0, "hits" : [ { - "_index" : "testindex", + "_index" : "national_parks", "_id" : "1", "_score" : 1.0, "_source" : { @@ -110,7 +110,7 @@ The response groups documents 2 and 3 together because they are close enough to } }, { - "_index" : "testindex", + "_index" : "national_parks", "_id" : "2", "_score" : 1.0, "_source" : { @@ -119,7 +119,7 @@ The response groups documents 2 and 3 together because they are close enough to } }, { - "_index" : "testindex", + "_index" : "national_parks", "_id" : "3", "_score" : 1.0, "_source" : { @@ -151,7 +151,7 @@ The response groups documents 2 and 3 together because they are close enough to Now run a higher precision request: ```json -GET testindex/_search +GET national_parks/_search { "aggregations": { "grouped": { @@ -184,7 +184,7 @@ All three documents are bucketed separately because of higher granularity: "max_score" : 1.0, "hits" : [ { - "_index" : "testindex", + "_index" : "national_parks", "_id" : "1", "_score" : 1.0, "_source" : { @@ -193,7 +193,7 @@ All three documents are bucketed separately because of higher granularity: } }, { - "_index" : "testindex", + "_index" : "national_parks", "_id" : "2", "_score" : 1.0, "_source" : { @@ -202,7 +202,7 @@ All three documents are bucketed separately because of higher granularity: } }, { - "_index" : "testindex", + "_index" : "national_parks", "_id" : "3", "_score" : 1.0, "_source" : { @@ -238,7 +238,7 @@ All three documents are bucketed separately because of higher granularity: High-precision requests are resource-intensive, so we recommend to use a filter like `geo_bounding_box` to limit the geographical area. For example, the following query applies a filter to limit the search area: ```json -GET testindex1/_search +GET national_parks/_search { "size" : 0, "aggregations": { @@ -304,6 +304,66 @@ The response contains the two documents that are within the `geo_bounding_box` b } ``` + You can also restrict the geographical area by providing the coordinates of the bounding envelope in the `bounds` parameter. Both `bounds` and `geo_bounding_box` coordinates can be specified in any of the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats). The following query uses the WKT "POINT(`longitude` `latitude`)" format for the `bounds` parameter: + +```json +GET national_parks/_search +{ + "size": 0, + "aggregations": { + "grouped": { + "geohex_grid": { + "field": "location", + "precision": 6, + "bounds": { + "top_left": "POINT (-120 38)", + "bottom_right": "POINT (-116 36)" + } + } + } + } +} +``` + +The response contains only the two results, which are within the specified bounds: + +```json +{ + "took" : 3, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 3, + "relation" : "eq" + }, + "max_score" : null, + "hits" : [ ] + }, + "aggregations" : { + "grouped" : { + "buckets" : [ + { + "key" : "8629ab6dfffffff", + "doc_count" : 1 + }, + { + "key" : "8629857a7ffffff", + "doc_count" : 1 + } + ] + } + } +} +``` + +The `bounds` parameter can be used with or without the `geo_bounding_box` filter; these two parameters are independent and can have any spatial relationship to each other. + ## Supported parameters GeoHex grid aggregation requests support the following parameters. @@ -312,6 +372,6 @@ Parameter | Data Type | Description :--- | :--- | :--- field | String | The field that contains the geopoints. This field must be mapped as a `geo_point` field. If the field contains an array, all array values are aggregated. Required. precision | Integer | The zoom level used to determine grid cells for bucketing results. Valid values are in the [0, 15] range. Default is 5. -bounds | Object | The bounding box for filtering geopoints. The bounding box is defined by the top left and bottom right vertices. The vertices are specified as geopoints in one of the following formats:
- An object with a latitude and longitude
- An array in the [`longitude`, `latitude`] format
- A string in the "`latitude`,`longitude`" format
- A geohash
- Well-known text (WKT).
See the [geopoint documentation]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) for format examples. Optional. +bounds | Object | The bounding box for filtering geopoints. The bounding box is defined by the top left and bottom right vertices. The vertices are specified as geopoints in one of the following formats:
- An object with a latitude and longitude
- An array in the [`longitude`, `latitude`] format
- A string in the "`latitude`,`longitude`" format
- A geohash
- Well-known text (WKT).
See the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) for format examples. Optional. size | Integer | The maximum number of buckets to return. When there are more buckets than `size`, OpenSearch returns buckets with more documents. Optional. Default is 10,000. shard_size | Integer | The maximum number of buckets to return from each shard. Optional. Default is max (10, `size` · number of shards), which gives a more accurate count of higher prioritized buckets. \ No newline at end of file From 2dc2c91840fed0694de79b036eaa96ecb9f20d85 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 2 Nov 2022 20:42:06 -0400 Subject: [PATCH 4/5] Incorporated doc review comments Signed-off-by: Fanit Kolchina --- _opensearch/geohexgrid-agg.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/_opensearch/geohexgrid-agg.md b/_opensearch/geohexgrid-agg.md index 55e7c9197f..629f8e98d0 100644 --- a/_opensearch/geohexgrid-agg.md +++ b/_opensearch/geohexgrid-agg.md @@ -8,7 +8,7 @@ has_children: false # GeoHex grid aggregations -The Hexagonal hierarchical geospatial indexing system (H3) partitions the Earth's areas into identifiable hexagon-shaped cells. +The Hexagonal Hierarchical Geospatial Indexing System (H3) partitions the Earth's areas into identifiable hexagon-shaped cells. The H3 grid system works well for proximity applications, because it overcomes the shortcomings of geohash's non-uniform partitions. Geohash encodes latitude and longitude pairs, leading to significantly smaller partitions near the poles and a degree of longitude near the equator. However, the H3 grid system's distortions are low and limited to five partitions of 122. These five partitions are placed in low-use areas (for example, in the middle of the ocean), leaving the essential areas error-free. Thus, grouping documents based on the H3 grid system provides a better aggregation than the geohash grid. @@ -235,7 +235,7 @@ All three documents are bucketed separately because of higher granularity: ## Filtering requests -High-precision requests are resource-intensive, so we recommend to use a filter like `geo_bounding_box` to limit the geographical area. For example, the following query applies a filter to limit the search area: +High-precision requests are resource-intensive, so we recommend using a filter like `geo_bounding_box` to limit the geographical area. For example, the following query applies a filter to limit the search area: ```json GET national_parks/_search @@ -304,7 +304,7 @@ The response contains the two documents that are within the `geo_bounding_box` b } ``` - You can also restrict the geographical area by providing the coordinates of the bounding envelope in the `bounds` parameter. Both `bounds` and `geo_bounding_box` coordinates can be specified in any of the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats). The following query uses the WKT "POINT(`longitude` `latitude`)" format for the `bounds` parameter: +You can also restrict the geographical area by providing the coordinates of the bounding envelope in the `bounds` parameter. Both `bounds` and `geo_bounding_box` coordinates can be specified in any of the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats). The following query uses the WKT "POINT(`longitude` `latitude`)" format for the `bounds` parameter: ```json GET national_parks/_search @@ -325,7 +325,7 @@ GET national_parks/_search } ``` -The response contains only the two results, which are within the specified bounds: +The response contains only the two results that are within the specified bounds: ```json { @@ -371,7 +371,7 @@ GeoHex grid aggregation requests support the following parameters. Parameter | Data Type | Description :--- | :--- | :--- field | String | The field that contains the geopoints. This field must be mapped as a `geo_point` field. If the field contains an array, all array values are aggregated. Required. -precision | Integer | The zoom level used to determine grid cells for bucketing results. Valid values are in the [0, 15] range. Default is 5. +precision | Integer | The zoom level used to determine grid cells for bucketing results. Valid values are in the [0, 15] range. Optional. Default is 5. bounds | Object | The bounding box for filtering geopoints. The bounding box is defined by the top left and bottom right vertices. The vertices are specified as geopoints in one of the following formats:
- An object with a latitude and longitude
- An array in the [`longitude`, `latitude`] format
- A string in the "`latitude`,`longitude`" format
- A geohash
- Well-known text (WKT).
See the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) for format examples. Optional. size | Integer | The maximum number of buckets to return. When there are more buckets than `size`, OpenSearch returns buckets with more documents. Optional. Default is 10,000. -shard_size | Integer | The maximum number of buckets to return from each shard. Optional. Default is max (10, `size` · number of shards), which gives a more accurate count of higher prioritized buckets. \ No newline at end of file +shard_size | Integer | The maximum number of buckets to return from each shard. Optional. Default is max (10, `size` · number of shards), which gives a more accurate count of higher-prioritized buckets. \ No newline at end of file From 2597ca5571701798c665a18bae99fd599d619cf6 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Thu, 3 Nov 2022 22:17:09 -0400 Subject: [PATCH 5/5] Incorporated editorial feedback Signed-off-by: Fanit Kolchina --- _opensearch/geohexgrid-agg.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/_opensearch/geohexgrid-agg.md b/_opensearch/geohexgrid-agg.md index 629f8e98d0..9e8e464824 100644 --- a/_opensearch/geohexgrid-agg.md +++ b/_opensearch/geohexgrid-agg.md @@ -10,7 +10,7 @@ has_children: false The Hexagonal Hierarchical Geospatial Indexing System (H3) partitions the Earth's areas into identifiable hexagon-shaped cells. -The H3 grid system works well for proximity applications, because it overcomes the shortcomings of geohash's non-uniform partitions. Geohash encodes latitude and longitude pairs, leading to significantly smaller partitions near the poles and a degree of longitude near the equator. However, the H3 grid system's distortions are low and limited to five partitions of 122. These five partitions are placed in low-use areas (for example, in the middle of the ocean), leaving the essential areas error-free. Thus, grouping documents based on the H3 grid system provides a better aggregation than the geohash grid. +The H3 grid system works well for proximity applications because it overcomes the limitations of Geohash's non-uniform partitions. Geohash encodes latitude and longitude pairs, leading to significantly smaller partitions near the poles and a degree of longitude near the equator. However, the H3 grid system's distortions are low and limited to 5 partitions of 122. These five partitions are placed in low-use areas (for example, in the middle of the ocean), leaving the essential areas error free. Thus, grouping documents based on the H3 grid system provides a better aggregation than the Geohash grid. The GeoHex grid aggregation groups [geopoints]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) into grid cells for geographical analysis. Each grid cell corresponds to an [H3 cell](https://h3geo.org/docs/core-library/h3Indexing/#h3-cell-indexp) and is identified using the [H3Index representation](https://h3geo.org/docs/core-library/h3Indexing/#h3index-representation). @@ -62,7 +62,7 @@ You can index geopoints in several formats. For a list of all supported formats, ## Low-precision requests -Run a low-precision request that should bucket all three documents together: +Run a low-precision request that buckets all three documents together: ```json GET national_parks/_search @@ -78,7 +78,7 @@ GET national_parks/_search } ``` -You can use either `GET` or `POST` HTTP method for GeoHex grid aggregation queries. +You can use either the `GET` or `POST` HTTP method for GeoHex grid aggregation queries. {: .note} The response groups documents 2 and 3 together because they are close enough to be bucketed in one grid cell: @@ -148,7 +148,7 @@ The response groups documents 2 and 3 together because they are close enough to ## High-precision requests -Now run a higher precision request: +Now run a high-precision request: ```json GET national_parks/_search @@ -235,7 +235,7 @@ All three documents are bucketed separately because of higher granularity: ## Filtering requests -High-precision requests are resource-intensive, so we recommend using a filter like `geo_bounding_box` to limit the geographical area. For example, the following query applies a filter to limit the search area: +High-precision requests are resource intensive, so we recommend using a filter like `geo_bounding_box` to limit the geographical area. For example, the following query applies a filter to limit the search area: ```json GET national_parks/_search @@ -304,7 +304,7 @@ The response contains the two documents that are within the `geo_bounding_box` b } ``` -You can also restrict the geographical area by providing the coordinates of the bounding envelope in the `bounds` parameter. Both `bounds` and `geo_bounding_box` coordinates can be specified in any of the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats). The following query uses the WKT "POINT(`longitude` `latitude`)" format for the `bounds` parameter: +You can also restrict the geographical area by providing the coordinates of the bounding envelope in the `bounds` parameter. Both `bounds` and `geo_bounding_box` coordinates can be specified in any of the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats). The following query uses the well-known text (WKT) "POINT(`longitude` `latitude`)" format for the `bounds` parameter: ```json GET national_parks/_search @@ -372,6 +372,6 @@ Parameter | Data Type | Description :--- | :--- | :--- field | String | The field that contains the geopoints. This field must be mapped as a `geo_point` field. If the field contains an array, all array values are aggregated. Required. precision | Integer | The zoom level used to determine grid cells for bucketing results. Valid values are in the [0, 15] range. Optional. Default is 5. -bounds | Object | The bounding box for filtering geopoints. The bounding box is defined by the top left and bottom right vertices. The vertices are specified as geopoints in one of the following formats:
- An object with a latitude and longitude
- An array in the [`longitude`, `latitude`] format
- A string in the "`latitude`,`longitude`" format
- A geohash
- Well-known text (WKT).
See the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) for format examples. Optional. +bounds | Object | The bounding box for filtering geopoints. The bounding box is defined by the top left and bottom right vertices. The vertices are specified as geopoints in one of the following formats:
- An object with a latitude and longitude
- An array in the [`longitude`, `latitude`] format
- A string in the "`latitude`,`longitude`" format
- A Geohash
- WKT
See the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) for formatting examples. Optional. size | Integer | The maximum number of buckets to return. When there are more buckets than `size`, OpenSearch returns buckets with more documents. Optional. Default is 10,000. -shard_size | Integer | The maximum number of buckets to return from each shard. Optional. Default is max (10, `size` · number of shards), which gives a more accurate count of higher-prioritized buckets. \ No newline at end of file +shard_size | Integer | The maximum number of buckets to return from each shard. Optional. Default is max (10, `size` · number of shards), which provides a more accurate count of more highly prioritized buckets. \ No newline at end of file