From e669834ef8f67ba886496feb29cadb7097fd7bab Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Thu, 6 Jul 2023 15:58:59 -0400 Subject: [PATCH 1/7] Add geohash and geotile grid aggregation on geoshapes documentation Signed-off-by: Fanit Kolchina --- .../aggregations/bucket/geohash-grid.md | 76 ++++++++++++++++++- .../aggregations/bucket/geotile-grid.md | 62 ++++++++++++++- 2 files changed, 135 insertions(+), 3 deletions(-) diff --git a/_query-dsl/aggregations/bucket/geohash-grid.md b/_query-dsl/aggregations/bucket/geohash-grid.md index dad820869b..1ccdc4fb30 100644 --- a/_query-dsl/aggregations/bucket/geohash-grid.md +++ b/_query-dsl/aggregations/bucket/geohash-grid.md @@ -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). @@ -65,4 +65,76 @@ GET opensearch_dashboards_sample_data_logs/_search 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. \ No newline at end of file +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 aggregate on geoshape fields, first create an index and map the `location` field as a `geo_shape`: + +```json +PUT national_parks +{ + "mappings": { + "properties": { + "location": { + "type": "geo_shape" + } + } + } +} +``` + +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] ]} +} + +PUT national_parks/_doc/2 +{ + "name": "Yosemite National Park", + "location": + {"type": "envelope","coordinates": [ [-120.23, 38.16], [-119.05, 37.45] ]} +} + +PUT national_parks/_doc/3 +{ + "name": "Death Valley National Park", + "location": + {"type": "envelope","coordinates": [ [-117.34, 37.01], [-116.38, 36.25] ]} +} +``` + +You can run an aggregation on the `location` field as follows: + +```json +GET national_parks/_search +{ + "aggregations": { + "grouped": { + "geohash_grid": { + "field": "location", + "precision": 3 + } + } + } +} +``` + +When aggregating geoshapes, one geoshape be counted for multiple buckets because it overlaps with multiple grid cells. + +## Supported parameters + +Geohash grid aggregation requests support the following parameters. + +Parameter | Data type | Description +:--- | :--- | :--- +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 and geoshapes. The bounding box is defined by the upper left and lower right vertices. Only shapes which 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:
- 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 provides a more accurate count of more highly prioritized buckets. \ No newline at end of file diff --git a/_query-dsl/aggregations/bucket/geotile-grid.md b/_query-dsl/aggregations/bucket/geotile-grid.md index e27c8f48a3..4211a674ad 100644 --- a/_query-dsl/aggregations/bucket/geotile-grid.md +++ b/_query-dsl/aggregations/bucket/geotile-grid.md @@ -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 @@ -313,6 +313,66 @@ The response contains only the two results that are within the specified bounds: 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 aggregate on geoshape fields, first create an index and map the `location` field as a `geo_shape`: + +```json +PUT national_parks +{ + "mappings": { + "properties": { + "location": { + "type": "geo_shape" + } + } + } +} +``` + +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] ]} +} + +PUT national_parks/_doc/2 +{ + "name": "Yosemite National Park", + "location": + {"type": "envelope","coordinates": [ [-120.23, 38.16], [-119.05, 37.45] ]} +} + +PUT national_parks/_doc/3 +{ + "name": "Death Valley National Park", + "location": + {"type": "envelope","coordinates": [ [-117.34, 37.01], [-116.38, 36.25] ]} +} +``` + +You can run an aggregation on the `location` field as follows: + +```json +GET national_parks/_search +{ + "aggregations": { + "grouped": { + "geotile_grid": { + "field": "location", + "precision": 3 + } + } + } +} +``` + +When aggregating geoshapes, one geoshape be counted for multiple buckets because it overlaps with multiple grid cells. + ## Supported parameters Geotile grid aggregation requests support the following parameters. From c8c78d4deea9edb880b91da46bad135c0a691545 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Tue, 11 Jul 2023 12:46:57 -0400 Subject: [PATCH 2/7] Add copy buttons and details blocks Signed-off-by: Fanit Kolchina --- .../aggregations/bucket/geohash-grid.md | 120 ++++++++++++- .../aggregations/bucket/geotile-grid.md | 163 +++++++++++++++++- 2 files changed, 279 insertions(+), 4 deletions(-) diff --git a/_query-dsl/aggregations/bucket/geohash-grid.md b/_query-dsl/aggregations/bucket/geohash-grid.md index 1ccdc4fb30..9c493f5b70 100644 --- a/_query-dsl/aggregations/bucket/geohash-grid.md +++ b/_query-dsl/aggregations/bucket/geohash-grid.md @@ -28,6 +28,7 @@ GET opensearch_dashboards_sample_data_logs/_search } } ``` +{% include copy-curl.html %} #### Example response @@ -83,6 +84,7 @@ PUT national_parks } } ``` +{% include copy-curl.html %} Next, index some documents into the `national_parks` index: @@ -93,14 +95,20 @@ PUT national_parks/_doc/1 "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", @@ -108,6 +116,7 @@ PUT national_parks/_doc/3 {"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: @@ -118,14 +127,121 @@ GET national_parks/_search "grouped": { "geohash_grid": { "field": "location", - "precision": 3 + "precision": 1 } } } } ``` +{% include copy-curl.html %} + +When aggregating geoshapes, one geoshape can be counted for multiple buckets because it overlaps with multiple grid cells: -When aggregating geoshapes, one geoshape be counted for multiple buckets because it overlaps with multiple grid cells. +
+ + Response + + {: .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 + } + ] + } + } +} +``` +
## Supported parameters diff --git a/_query-dsl/aggregations/bucket/geotile-grid.md b/_query-dsl/aggregations/bucket/geotile-grid.md index 4211a674ad..a242b37284 100644 --- a/_query-dsl/aggregations/bucket/geotile-grid.md +++ b/_query-dsl/aggregations/bucket/geotile-grid.md @@ -30,6 +30,7 @@ PUT national_parks } } ``` +{% include copy-curl.html %} Index the following documents into the sample index: @@ -39,19 +40,26 @@ PUT national_parks/_doc/1 "name": "Yellowstone National Park", "location": "44.42, -110.59" } +``` +{% include copy-curl.html %} +```json PUT national_parks/_doc/2 { "name": "Yosemite National Park", "location": "37.87, -119.53" } +``` +{% include copy-curl.html %} +```json PUT national_parks/_doc/3 { "name": "Death Valley National Park", "location": "36.53, -116.93" } ``` +{% include copy-curl.html %} 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} @@ -73,12 +81,19 @@ GET national_parks/_search } } ``` +{% include copy-curl.html %} You can use either the `GET` or `POST` HTTP method for geotile grid aggregation queries. {: .note} The response groups all documents together because they are close enough to be bucketed in one grid cell: +
+ + Response + + {: .text-delta} + ```json { "took": 51, @@ -137,6 +152,7 @@ The response groups all documents together because they are close enough to be b } } ``` +
## High-precision requests @@ -155,9 +171,16 @@ GET national_parks/_search } } ``` +{% include copy-curl.html %} All three documents are bucketed separately because of higher granularity: +
+ + Response + + {: .text-delta} + ```json { "took": 15, @@ -224,6 +247,7 @@ All three documents are bucketed separately because of higher granularity: } } ``` +
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: @@ -245,9 +269,16 @@ GET national_parks/_search } } ``` +{% include copy-curl.html %} The response contains only the two results that are within the specified bounds: +
+ + Response + + {: .text-delta} + ```json { "took": 48, @@ -310,6 +341,7 @@ The response contains only the two results that are within the specified bounds: } } ``` +
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. @@ -329,6 +361,7 @@ PUT national_parks } } ``` +{% include copy-curl.html %} Next, index some documents into the `national_parks` index: @@ -339,14 +372,20 @@ PUT national_parks/_doc/1 "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", @@ -354,6 +393,7 @@ PUT national_parks/_doc/3 {"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: @@ -364,14 +404,133 @@ GET national_parks/_search "grouped": { "geotile_grid": { "field": "location", - "precision": 3 + "precision": 6 } } } } ``` +{% include copy-curl.html %} + +When aggregating geoshapes, one geoshape can be counted for multiple buckets because it overlaps with multiple grid cells: -When aggregating geoshapes, one geoshape be counted for multiple buckets because it overlaps with multiple grid cells. +
+ + Response + + {: .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 + } + ] + } + } +} +``` +
## Supported parameters From ee32544faccaf31207545c513d54e0f23a5ca002 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 12 Jul 2023 12:17:33 -0400 Subject: [PATCH 3/7] Add note about geoshape agg not supported for visualizations Signed-off-by: Fanit Kolchina --- .../aggregations/bucket/geohash-grid.md | 3 + .../aggregations/bucket/geotile-grid.md | 3 + _query-dsl/aggregations/metric/geobounds.md | 185 +++++++++++++++++- 3 files changed, 188 insertions(+), 3 deletions(-) diff --git a/_query-dsl/aggregations/bucket/geohash-grid.md b/_query-dsl/aggregations/bucket/geohash-grid.md index 9c493f5b70..33fbe84aa1 100644 --- a/_query-dsl/aggregations/bucket/geohash-grid.md +++ b/_query-dsl/aggregations/bucket/geohash-grid.md @@ -243,6 +243,9 @@ When aggregating geoshapes, one geoshape can be counted for multiple buckets bec ``` +Currently, OpenSearch supports geoshape aggregations through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregations 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. diff --git a/_query-dsl/aggregations/bucket/geotile-grid.md b/_query-dsl/aggregations/bucket/geotile-grid.md index 1ae5792d2a..5765d89ab5 100644 --- a/_query-dsl/aggregations/bucket/geotile-grid.md +++ b/_query-dsl/aggregations/bucket/geotile-grid.md @@ -532,6 +532,9 @@ When aggregating geoshapes, one geoshape can be counted for multiple buckets bec ``` +Currently, OpenSearch supports geoshape aggregations through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregations 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. diff --git a/_query-dsl/aggregations/metric/geobounds.md b/_query-dsl/aggregations/metric/geobounds.md index f78ece2397..2df7418294 100644 --- a/_query-dsl/aggregations/metric/geobounds.md +++ b/_query-dsl/aggregations/metric/geobounds.md @@ -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) that contains 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 } } } -``` \ No newline at end of file +``` + +## Aggregating geoshapes + +To aggregate on geoshape fields, 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° meridian). If `wrap_longitude` is set to `true`, the bounding box can overlap the international date line and return a bounds where the lower-left longitude is larger 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: + +
+ + Response + + {: .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 + } + } + } + } +} +``` +
+ +Currently, OpenSearch supports geoshape aggregations through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregations implemented for visualizations, upvote the related [GitHub issue](https://github.com/opensearch-project/dashboards-maps/issues/250). +{: .note} From 1d73dc7d888778673ceef8d966d1c2a8c9752911 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Mon, 17 Jul 2023 12:27:36 -0400 Subject: [PATCH 4/7] Update _query-dsl/aggregations/bucket/geohash-grid.md Co-authored-by: Melissa Vagi Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _query-dsl/aggregations/bucket/geohash-grid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_query-dsl/aggregations/bucket/geohash-grid.md b/_query-dsl/aggregations/bucket/geohash-grid.md index 33fbe84aa1..d84a0f8f17 100644 --- a/_query-dsl/aggregations/bucket/geohash-grid.md +++ b/_query-dsl/aggregations/bucket/geohash-grid.md @@ -254,6 +254,6 @@ Parameter | Data type | Description :--- | :--- | :--- 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 and geoshapes. The bounding box is defined by the upper left and lower right vertices. Only shapes which 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:
- 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. +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:
- 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 provides a more accurate count of more highly prioritized buckets. \ No newline at end of file From 561c368018608c3becbf78eb71064cd2afd15ef4 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Mon, 17 Jul 2023 14:14:36 -0400 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _query-dsl/aggregations/bucket/geohash-grid.md | 8 ++++---- _query-dsl/aggregations/bucket/geotile-grid.md | 4 ++-- _query-dsl/aggregations/metric/geobounds.md | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/_query-dsl/aggregations/bucket/geohash-grid.md b/_query-dsl/aggregations/bucket/geohash-grid.md index d84a0f8f17..cb42969f98 100644 --- a/_query-dsl/aggregations/bucket/geohash-grid.md +++ b/_query-dsl/aggregations/bucket/geohash-grid.md @@ -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. 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 `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). @@ -66,7 +66,7 @@ GET opensearch_dashboards_sample_data_logs/_search 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. +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 @@ -135,7 +135,7 @@ GET national_parks/_search ``` {% include copy-curl.html %} -When aggregating geoshapes, one geoshape can be counted for multiple buckets because it overlaps with multiple grid cells: +When aggregating geoshapes, one geoshape can be counted for multiple buckets because it overlaps multiple grid cells:
@@ -243,7 +243,7 @@ When aggregating geoshapes, one geoshape can be counted for multiple buckets bec ```
-Currently, OpenSearch supports geoshape aggregations through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregations implemented for visualizations, upvote the related [GitHub issue](https://github.com/opensearch-project/dashboards-maps/issues/250). +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 diff --git a/_query-dsl/aggregations/bucket/geotile-grid.md b/_query-dsl/aggregations/bucket/geotile-grid.md index 5765d89ab5..f09007ccf3 100644 --- a/_query-dsl/aggregations/bucket/geotile-grid.md +++ b/_query-dsl/aggregations/bucket/geotile-grid.md @@ -8,7 +8,7 @@ nav_order: 87 # Geotile grid aggregations -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. +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 @@ -532,7 +532,7 @@ When aggregating geoshapes, one geoshape can be counted for multiple buckets bec ``` -Currently, OpenSearch supports geoshape aggregations through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregations implemented for visualizations, upvote the related [GitHub issue](https://github.com/opensearch-project/dashboards-maps/issues/250). +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 diff --git a/_query-dsl/aggregations/metric/geobounds.md b/_query-dsl/aggregations/metric/geobounds.md index 2df7418294..a50bfed53b 100644 --- a/_query-dsl/aggregations/metric/geobounds.md +++ b/_query-dsl/aggregations/metric/geobounds.md @@ -8,7 +8,7 @@ nav_order: 40 ## Geobounds aggregations -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) that contains 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 `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: @@ -223,5 +223,5 @@ The response contains the geo-bounding box that encloses all shapes in the `loca ``` -Currently, OpenSearch supports geoshape aggregations through the API but not in OpenSearch Dashboards visualizations. If you'd like to see geoshape aggregations implemented for visualizations, upvote the related [GitHub issue](https://github.com/opensearch-project/dashboards-maps/issues/250). +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} From 7c404c34d42ce14b2b0349a5709f70b9bde5ffd6 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 17 Jul 2023 16:39:03 -0400 Subject: [PATCH 6/7] Add editorial comments Signed-off-by: Fanit Kolchina --- _query-dsl/aggregations/bucket/geohash-grid.md | 2 +- _query-dsl/aggregations/bucket/geotile-grid.md | 2 +- _query-dsl/aggregations/metric/geobounds.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/_query-dsl/aggregations/bucket/geohash-grid.md b/_query-dsl/aggregations/bucket/geohash-grid.md index 33fbe84aa1..a1677160f4 100644 --- a/_query-dsl/aggregations/bucket/geohash-grid.md +++ b/_query-dsl/aggregations/bucket/geohash-grid.md @@ -70,7 +70,7 @@ The more accurate you want the aggregation to be, the more resources OpenSearch ## Aggregating geoshapes -To aggregate on geoshape fields, first create an index and map the `location` field as a `geo_shape`: +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 diff --git a/_query-dsl/aggregations/bucket/geotile-grid.md b/_query-dsl/aggregations/bucket/geotile-grid.md index 5765d89ab5..d80f129414 100644 --- a/_query-dsl/aggregations/bucket/geotile-grid.md +++ b/_query-dsl/aggregations/bucket/geotile-grid.md @@ -347,7 +347,7 @@ The `bounds` parameter can be used with or without the `geo_bounding_box` filter ## Aggregating geoshapes -To aggregate on geoshape fields, first create an index and map the `location` field as a `geo_shape`: +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 diff --git a/_query-dsl/aggregations/metric/geobounds.md b/_query-dsl/aggregations/metric/geobounds.md index 2df7418294..a6078c43ed 100644 --- a/_query-dsl/aggregations/metric/geobounds.md +++ b/_query-dsl/aggregations/metric/geobounds.md @@ -48,7 +48,7 @@ GET opensearch_dashboards_sample_data_ecommerce/_search ## Aggregating geoshapes -To aggregate on geoshape fields, first create an index and map the `location` field as a `geo_shape`: +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 From 30acd3ff1730281a9d7b760135df7d78bf61c10f Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Tue, 18 Jul 2023 10:23:49 -0400 Subject: [PATCH 7/7] Reworded bounds Signed-off-by: Fanit Kolchina --- _query-dsl/aggregations/metric/geobounds.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_query-dsl/aggregations/metric/geobounds.md b/_query-dsl/aggregations/metric/geobounds.md index eaa2603624..24b86a8d75 100644 --- a/_query-dsl/aggregations/metric/geobounds.md +++ b/_query-dsl/aggregations/metric/geobounds.md @@ -113,7 +113,7 @@ GET national_parks/_search ``` {% 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° meridian). If `wrap_longitude` is set to `true`, the bounding box can overlap the international date line and return a bounds where the lower-left longitude is larger than the upper-right longitude. The default value for `wrap_longitude` is `true`. +The optional `wrap_longitude` parameter specifies whether the bounding box returned by the aggregation can overlap the international date line (180° 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: