Adds GeoHex grid documentation #1761
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: Fanit Kolchina <[email protected]>
kolchfa-aws
added
3 - Tech review
Signed-off-by: Fanit Kolchina <[email protected]>
VijayanB
reviewed
Nov 1, 2022
_opensearch/geohexgrid-agg.md
Outdated
| To start, create an index and map the `location` field as geopoint: | ||
|
|
||
| ```json | ||
| PUT testindex |
There was a problem hiding this comment.
nit
Suggested change
| PUT testindex | |
| PUT national_parks |
VijayanB
reviewed
Nov 1, 2022
_opensearch/geohexgrid-agg.md
Outdated
|
|
||
| The following example illustrates low-precision and high-precision aggregation requests. | ||
|
|
||
| To start, create an index and map the `location` field as geopoint: |
There was a problem hiding this comment.
Suggested change
| To start, create an index and map the `location` field as geopoint: | |
| To start, create an index and map the `location` field as geo_point: |
Signed-off-by: Fanit Kolchina <[email protected]>
VijayanB
approved these changes
Nov 2, 2022
vagimeli
approved these changes
Nov 2, 2022
_opensearch/geohexgrid-agg.md
Outdated
|
|
||
| # GeoHex grid aggregations | ||
|
|
||
| The Hexagonal hierarchical geospatial indexing system (H3) partitions the Earth's areas into identifiable hexagon-shaped cells. |
There was a problem hiding this comment.
This is a funny one. It's a proper name, so it should be written as Hexagonal Hierarchical Geospatial Indexing System (H3). Uber refers to it as H3 on first mention, ignoring capitalization standards for proper names. It's their product though, so they can do what they want. I'd follow capitalization standards for proper names in our documentation.
_opensearch/geohexgrid-agg.md
Outdated
|
|
||
| ## Low-precision requests | ||
|
|
||
| Run a low-precision request that should bucket all three documents together: |
There was a problem hiding this comment.
Should this read "..that buckets all..."
There was a problem hiding this comment.
This is what's expected to happen after you run this request.
There was a problem hiding this comment.
I agree that "should" reads strangely here and would go with @vagimeli suggestion, if accurate.
_opensearch/geohexgrid-agg.md
Outdated
|
|
||
| ## 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: |
There was a problem hiding this comment.
Suggested revision: "..., so we recommend using a filter..."
_opensearch/geohexgrid-agg.md
Outdated
| } | ||
| ``` | ||
|
|
||
| The response contains only the two results, which are within the specified bounds: |
There was a problem hiding this comment.
Change "...two results, which" to "two results that"
_opensearch/geohexgrid-agg.md
Outdated
| 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: <br>- An object with a latitude and longitude<br>- An array in the [`longitude`, `latitude`] format<br>- A string in the "`latitude`,`longitude`" format<br>- A geohash <br>- Well-known text (WKT).<br> 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. |
There was a problem hiding this comment.
Change "higher prioritized" to "higher-prioritized"
ariamarble
reviewed
Nov 2, 2022
_opensearch/geohexgrid-agg.md
Outdated
| } | ||
| ``` | ||
|
|
||
| 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: |
There was a problem hiding this comment.
Suggested change
| 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: |
ariamarble
reviewed
Nov 2, 2022
_opensearch/geohexgrid-agg.md
Outdated
| 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. |
There was a problem hiding this comment.
Is this one optional or required?
ariamarble
approved these changes
Nov 2, 2022
Signed-off-by: Fanit Kolchina <[email protected]>
natebower
reviewed
Nov 3, 2022
There was a problem hiding this comment.
@kolchfa-aws Please see my comments and changes and let me know if you have any questions.
_opensearch/geohexgrid-agg.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
Suggested change
| 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 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 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. |
_opensearch/geohexgrid-agg.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
I would try to avoid "overcomes the shortcomings" (replace one of them with a synonym). Should "geohash" be capitalized in the two instances where it is lowercase?
There was a problem hiding this comment.
Replaced with "overcomes the limitations". Geohash is lowercase in general.
There was a problem hiding this comment.
Just checked, and Geohash is capitalized. Will change.
_opensearch/geohexgrid-agg.md
Outdated
|
|
||
| ## Low-precision requests | ||
|
|
||
| Run a low-precision request that should bucket all three documents together: |
There was a problem hiding this comment.
I agree that "should" reads strangely here and would go with @vagimeli suggestion, if accurate.
_opensearch/geohexgrid-agg.md
Outdated
| } | ||
| ``` | ||
|
|
||
| You can use either `GET` or `POST` HTTP method for GeoHex grid aggregation queries. |
There was a problem hiding this comment.
Should this read "You can use either the GET or POST HTTP method for..."?
_opensearch/geohexgrid-agg.md
Outdated
|
|
||
| ## High-precision requests | ||
|
|
||
| Now run a higher precision request: |
There was a problem hiding this comment.
Suggested change
| Now run a higher precision request: | |
| Now run a high-precision request: |
_opensearch/geohexgrid-agg.md
Outdated
| } | ||
| ``` | ||
|
|
||
| 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: |
There was a problem hiding this comment.
Suggested change
| 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: |
_opensearch/geohexgrid-agg.md
Outdated
| :--- | :--- | :--- | ||
| 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: <br>- An object with a latitude and longitude<br>- An array in the [`longitude`, `latitude`] format<br>- A string in the "`latitude`,`longitude`" format<br>- A geohash <br>- Well-known text (WKT).<br> See the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) for format examples. Optional. |
There was a problem hiding this comment.
Suggested change
| 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: <br>- An object with a latitude and longitude<br>- An array in the [`longitude`, `latitude`] format<br>- A string in the "`latitude`,`longitude`" format<br>- A geohash <br>- Well-known text (WKT).<br> 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: <br>- An object with a latitude and longitude<br>- An array in the [`longitude`, `latitude`] format<br>- A string in the "`latitude`,`longitude`" format<br>- A geohash <br>- WKT<br> See the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) for format examples. Optional. |
_opensearch/geohexgrid-agg.md
Outdated
| :--- | :--- | :--- | ||
| 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: <br>- An object with a latitude and longitude<br>- An array in the [`longitude`, `latitude`] format<br>- A string in the "`latitude`,`longitude`" format<br>- A geohash <br>- Well-known text (WKT).<br> See the [geopoint formats]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) for format examples. Optional. |
There was a problem hiding this comment.
Should "geohash" be capitalized? "for formatting examples"?
_opensearch/geohexgrid-agg.md
Outdated
| 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: <br>- An object with a latitude and longitude<br>- An array in the [`longitude`, `latitude`] format<br>- A string in the "`latitude`,`longitude`" format<br>- A geohash <br>- Well-known text (WKT).<br> 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| 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 higher-prioritized buckets. |
_opensearch/geohexgrid-agg.md
Outdated
| 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: <br>- An object with a latitude and longitude<br>- An array in the [`longitude`, `latitude`] format<br>- A string in the "`latitude`,`longitude`" format<br>- A geohash <br>- Well-known text (WKT).<br> 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. |
There was a problem hiding this comment.
"more highly prioritized buckets"?
Signed-off-by: Fanit Kolchina <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes #1100
Checklist
For more information on following Developer Certificate of Origin and signing off your commits, please check here.