iSharkFly-Docs
/
opensearch-docs-cn
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add geohash, geotile, and geobounds aggregation on geoshapes documentation (#4517) 

* Add geohash and geotile grid aggregation on geoshapes documentation

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Add copy buttons and details blocks

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Add note about geoshape agg not supported for visualizations

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Update _query-dsl/aggregations/bucket/geohash-grid.md

Co-authored-by: Melissa Vagi <vagimeli@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Nathan Bower <nbower@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Add editorial comments

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Reworded bounds

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

---------

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Co-authored-by: Melissa Vagi <vagimeli@amazon.com>
Co-authored-by: Nathan Bower <nbower@amazon.com>
This commit is contained in:
kolchfa-aws 2023-07-18 10:58:30 -04:00 committed by GitHub
parent 6c83dfd87c
commit 42e8a1bdca
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 575 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
_query-dsl/aggregations/bucket/geohash-grid.md
View File

@ -8,7 +8,7 @@ nav_order: 80
# Geohash grid aggregations
The `geohash_grid` aggregation buckets documents for geographical analysis. It organizes a geographical region into a grid of smaller regions of different sizes or precisions. Lower values of precision represent larger geographical areas and higher values represent smaller, more precise geographical areas.
The `geohash_grid` aggregation buckets documents for geographical analysis. It organizes a geographical region into a grid of smaller regions of different sizes or precisions. Lower values of precision represent larger geographical areas, and higher values represent smaller, more precise geographical areas. You can aggregate documents on [geopoint]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) or [geoshape]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-shape/) fields using a geohash grid aggregation. One notable difference is that a geopoint is only present in one bucket, but a geoshape is counted in all geohash grid cells with which it intersects.
The number of results returned by a query might be far too many to display each geopoint individually on a map. The `geohash_grid` aggregation buckets nearby geopoints together by calculating the geohash for each point, at the level of precision that you define (between 1 to 12; the default is 5). To learn more about geohash, see [Wikipedia](https://en.wikipedia.org/wiki/Geohash).
@ -68,14 +68,192 @@ You can visualize the aggregated response on a map using OpenSearch Dashboards.
The more accurate you want the aggregation to be, the more resources OpenSearch consumes because of the number of buckets that the aggregation has to calculate. By default, OpenSearch does not generate more than 10,000 buckets. You can change this behavior by using the `size` attribute, but keep in mind that the performance might suffer for very wide queries consisting of thousands of buckets.
## Aggregating geoshapes
To run an aggregation on a geoshape field, first create an index and map the `location` field as a `geo_shape`:
```json
PUT national_parks
{
"mappings": {
"properties": {
"location": {
"type": "geo_shape"
}
}
}
}
```
{% include copy-curl.html %}
Next, index some documents into the `national_parks` index:
```json
PUT national_parks/_doc/1
{
"name": "Yellowstone National Park",
"location":
{"type": "envelope","coordinates": [ [-111.15, 45.12], [-109.83, 44.12] ]}
}
```
{% include copy-curl.html %}
```json
PUT national_parks/_doc/2
{
"name": "Yosemite National Park",
"location":
{"type": "envelope","coordinates": [ [-120.23, 38.16], [-119.05, 37.45] ]}
}
```
{% include copy-curl.html %}
```json
PUT national_parks/_doc/3
{
"name": "Death Valley National Park",
"location":
{"type": "envelope","coordinates": [ [-117.34, 37.01], [-116.38, 36.25] ]}
}
```
{% include copy-curl.html %}
You can run an aggregation on the `location` field as follows:
```json
GET national_parks/_search
{
"aggregations": {
"grouped": {
"geohash_grid": {
"field": "location",
"precision": 1
}
}
}
}
```
{% include copy-curl.html %}
When aggregating geoshapes, one geoshape can be counted for multiple buckets because it overlaps multiple grid cells:
<details open markdown="block">
<summary>
Response
</summary>
{: .text-delta}
```json
{
"took" : 24,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 3,
"relation" : "eq"
},
"max_score" : 1.0,
"hits" : [
{
"_index" : "national_parks",
"_id" : "1",
"_score" : 1.0,
"_source" : {
"name" : "Yellowstone National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-111.15,
45.12
],
[
-109.83,
44.12
]
]
}
}
},
{
"_index" : "national_parks",
"_id" : "2",
"_score" : 1.0,
"_source" : {
"name" : "Yosemite National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-120.23,
38.16
],
[
-119.05,
37.45
]
]
}
}
},
{
"_index" : "national_parks",
"_id" : "3",
"_score" : 1.0,
"_source" : {
"name" : "Death Valley National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-117.34,
37.01
],
[
-116.38,
36.25
]
]
}
}
}
]
},
"aggregations" : {
"grouped" : {
"buckets" : [
{
"key" : "9",
"doc_count" : 3
},
{
"key" : "c",
"doc_count" : 1
}
]
}
}
}
```
</details>
Currently, OpenSearch supports geoshape aggregation through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregation implemented for visualizations, upvote the related [GitHub issue](https://github.com/opensearch-project/dashboards-maps/issues/250).
{: .note}
## Supported parameters
Geohash 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.
field | String | The field on which aggregation is performed. This field must be mapped as a `geo_point` or `geo_shape` 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 upper-left and lower-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 formatting examples. Optional.
bounds | Object | The bounding box for filtering geopoints and geoshapes. The bounding box is defined by the upper-left and lower-right vertices. Only shapes that intersect with this bounding box or are completely enclosed by this bounding box are included in the aggregation output. 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 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` &middot; number of shards), which provides a more accurate count of more highly prioritized buckets.

213
_query-dsl/aggregations/bucket/geotile-grid.md
View File

@ -8,7 +8,7 @@ nav_order: 87
# Geotile grid aggregations
The geotile 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 a [map tile](https://en.wikipedia.org/wiki/Tiled_web_map) and is identified using the `{zoom}/{x}/{y}` format.
The geotile grid aggregation groups documents into grid cells for geographical analysis. Each grid cell corresponds to a [map tile](https://en.wikipedia.org/wiki/Tiled_web_map) and is identified using the `{zoom}/{x}/{y}` format. You can aggregate documents on [geopoint]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) or [geoshape]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-shape/) fields using a geotile grid aggregation. One notable difference is that a geopoint is only present in one bucket, but a geoshape is counted in all geotile grid cells with which it intersects.
## Precision
@ -88,6 +88,12 @@ You can use either the `GET` or `POST` HTTP method for geotile grid aggregation
The response groups all documents together because they are close enough to be bucketed in one grid cell:
<details open markdown="block">
<summary>
Response
</summary>
{: .text-delta}
```json
{
"took": 51,
@ -146,6 +152,7 @@ The response groups all documents together because they are close enough to be b
}
}
```
</details>
## High-precision requests
@ -168,6 +175,12 @@ GET national_parks/_search
All three documents are bucketed separately because of higher granularity:
<details open markdown="block">
<summary>
Response
</summary>
{: .text-delta}
```json
{
"took": 15,
@ -234,6 +247,7 @@ All three documents are bucketed separately because of higher granularity:
}
}
```
</details>
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:
@ -259,6 +273,12 @@ GET national_parks/_search
The response contains only the two results that are within the specified bounds:
<details open markdown="block">
<summary>
Response
</summary>
{: .text-delta}
```json
{
"took": 48,
@ -321,9 +341,200 @@ The response contains only the two results that are within the specified bounds:
}
}
```
</details>
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.
## Aggregating geoshapes
To run an aggregation on a geoshape field, first create an index and map the `location` field as a `geo_shape`:
```json
PUT national_parks
{
"mappings": {
"properties": {
"location": {
"type": "geo_shape"
}
}
}
}
```
{% include copy-curl.html %}
Next, index some documents into the `national_parks` index:
```json
PUT national_parks/_doc/1
{
"name": "Yellowstone National Park",
"location":
{"type": "envelope","coordinates": [ [-111.15, 45.12], [-109.83, 44.12] ]}
}
```
{% include copy-curl.html %}
```json
PUT national_parks/_doc/2
{
"name": "Yosemite National Park",
"location":
{"type": "envelope","coordinates": [ [-120.23, 38.16], [-119.05, 37.45] ]}
}
```
{% include copy-curl.html %}
```json
PUT national_parks/_doc/3
{
"name": "Death Valley National Park",
"location":
{"type": "envelope","coordinates": [ [-117.34, 37.01], [-116.38, 36.25] ]}
}
```
{% include copy-curl.html %}
You can run an aggregation on the `location` field as follows:
```json
GET national_parks/_search
{
"aggregations": {
"grouped": {
"geotile_grid": {
"field": "location",
"precision": 6
}
}
}
}
```
{% include copy-curl.html %}
When aggregating geoshapes, one geoshape can be counted for multiple buckets because it overlaps with multiple grid cells:
<details open markdown="block">
<summary>
Response
</summary>
{: .text-delta}
```json
{
"took" : 3,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 3,
"relation" : "eq"
},
"max_score" : 1.0,
"hits" : [
{
"_index" : "national_parks",
"_id" : "1",
"_score" : 1.0,
"_source" : {
"name" : "Yellowstone National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-111.15,
45.12
],
[
-109.83,
44.12
]
]
}
}
},
{
"_index" : "national_parks",
"_id" : "2",
"_score" : 1.0,
"_source" : {
"name" : "Yosemite National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-120.23,
38.16
],
[
-119.05,
37.45
]
]
}
}
},
{
"_index" : "national_parks",
"_id" : "3",
"_score" : 1.0,
"_source" : {
"name" : "Death Valley National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-117.34,
37.01
],
[
-116.38,
36.25
]
]
}
}
}
]
},
"aggregations" : {
"grouped" : {
"buckets" : [
{
"key" : "6/12/23",
"doc_count" : 1
},
{
"key" : "6/12/22",
"doc_count" : 1
},
{
"key" : "6/11/25",
"doc_count" : 1
},
{
"key" : "6/11/24",
"doc_count" : 1
},
{
"key" : "6/10/24",
"doc_count" : 1
}
]
}
}
}
```
</details>
Currently, OpenSearch supports geoshape aggregation through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregation implemented for visualizations, upvote the related [GitHub issue](https://github.com/opensearch-project/dashboards-maps/issues/250).
{: .note}
## Supported parameters
Geotile grid aggregation requests support the following parameters.

185
_query-dsl/aggregations/metric/geobounds.md
View File

@ -8,7 +8,7 @@ nav_order: 40
## Geobounds aggregations
The `geo_bounds` metric is a multi-value metric aggregation that calculates the bounding box in terms of latitude and longitude around a `geo_point` field.
The `geo_bounds` metric is a multi-value metric aggregation that calculates the [geographic bounding box](https://docs.ogc.org/is/12-063r5/12-063r5.html#30) containing all values of a given `geo_point` or `geo_shape` field. The bounding box is returned as the upper-left and lower-right vertices of the rectangle in terms of latitude and longitude.
The following example returns the `geo_bounds` metrics for the `geoip.location` field:
@ -25,7 +25,6 @@ GET opensearch_dashboards_sample_data_ecommerce/_search
}
}
```
{% include copy-curl.html %}
#### Example response
@ -45,4 +44,184 @@ GET opensearch_dashboards_sample_data_ecommerce/_search
}
}
}
```
```
## Aggregating geoshapes
To run an aggregation on a geoshape field, first create an index and map the `location` field as a `geo_shape`:
```json
PUT national_parks
{
"mappings": {
"properties": {
"location": {
"type": "geo_shape"
}
}
}
}
```
{% include copy-curl.html %}
Next, index some documents into the `national_parks` index:
```json
PUT national_parks/_doc/1
{
"name": "Yellowstone National Park",
"location":
{"type": "envelope","coordinates": [ [-111.15, 45.12], [-109.83, 44.12] ]}
}
```
{% include copy-curl.html %}
```json
PUT national_parks/_doc/2
{
"name": "Yosemite National Park",
"location":
{"type": "envelope","coordinates": [ [-120.23, 38.16], [-119.05, 37.45] ]}
}
```
{% include copy-curl.html %}
```json
PUT national_parks/_doc/3
{
"name": "Death Valley National Park",
"location":
{"type": "envelope","coordinates": [ [-117.34, 37.01], [-116.38, 36.25] ]}
}
```
{% include copy-curl.html %}
You can run a `geo_bounds` aggregation on the `location` field as follows:
```json
GET national_parks/_search
{
"aggregations": {
"grouped": {
"geo_bounds": {
"field": "location",
"wrap_longitude": true
}
}
}
}
```
{% include copy-curl.html %}
The optional `wrap_longitude` parameter specifies whether the bounding box returned by the aggregation can overlap the international date line (180&deg; meridian). If `wrap_longitude` is set to `true`, the bounding box can overlap the international date line and return a `bounds` object in which the lower-left longitude is greater than the upper-right longitude. The default value for `wrap_longitude` is `true`.
The response contains the geo-bounding box that encloses all shapes in the `location` field:
<details open markdown="block">
<summary>
Response
</summary>
{: .text-delta}
```json
{
"took" : 3,
"timed_out" : false,
"_shards" : {
"total" : 1,
"successful" : 1,
"skipped" : 0,
"failed" : 0
},
"hits" : {
"total" : {
"value" : 3,
"relation" : "eq"
},
"max_score" : 1.0,
"hits" : [
{
"_index" : "national_parks",
"_id" : "1",
"_score" : 1.0,
"_source" : {
"name" : "Yellowstone National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-111.15,
45.12
],
[
-109.83,
44.12
]
]
}
}
},
{
"_index" : "national_parks",
"_id" : "2",
"_score" : 1.0,
"_source" : {
"name" : "Yosemite National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-120.23,
38.16
],
[
-119.05,
37.45
]
]
}
}
},
{
"_index" : "national_parks",
"_id" : "3",
"_score" : 1.0,
"_source" : {
"name" : "Death Valley National Park",
"location" : {
"type" : "envelope",
"coordinates" : [
[
-117.34,
37.01
],
[
-116.38,
36.25
]
]
}
}
}
]
},
"aggregations" : {
"Grouped" : {
"bounds" : {
"top_left" : {
"lat" : 45.11999997776002,
"lon" : -120.23000006563962
},
"bottom_right" : {
"lat" : 36.249999976716936,
"lon" : -109.83000006526709
}
}
}
}
}
```
</details>
Currently, OpenSearch supports geoshape aggregation through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregation implemented for visualizations, upvote the related [GitHub issue](https://github.com/opensearch-project/dashboards-maps/issues/250).
{: .note}