From 9a69d6a200dfc3a5fdbde26e2150fd9776d77b31 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 5 Dec 2022 16:48:28 -0500 Subject: [PATCH 1/5] Adds geo-bounding box query documentation Signed-off-by: Fanit Kolchina --- _opensearch/query-dsl/geo-bounding-box.md | 183 ++++++++++++++++++ .../supported-field-types/geo-point.md | 1 + 2 files changed, 184 insertions(+) create mode 100644 _opensearch/query-dsl/geo-bounding-box.md diff --git a/_opensearch/query-dsl/geo-bounding-box.md b/_opensearch/query-dsl/geo-bounding-box.md new file mode 100644 index 00000000000..45829a12852 --- /dev/null +++ b/_opensearch/query-dsl/geo-bounding-box.md @@ -0,0 +1,183 @@ +--- +layout: default +title: Geo-bounding box queries +parent: Query DSL +nav_order: 55 +--- + +# Geo-bounding box queries + +To search for documents that contain [geopoint]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point) fields, use a geo-bounding box query. The geo-bounding box query returns documents whose geopoints are within the bounding box specified in the query. A document with multiple geopoints matches the query if at least one geopoint is within the bounding box. + +## Example + +You can use a geo-bounding box query to search for documents that contain geopoints. + +Create a mapping with the `point` field is mapped as `geo_point`: + +```json +PUT testindex1 +{ + "mappings": { + "properties": { + "point": { + "type": "geo_point" + }, + "shape": { + "type": "geo_shape" + } + } + } +} +``` + +Index three geopoints as objects with latitudes and longitudes: + +```json +PUT testindex1/_doc/1 +{ + "point": { + "lat": 74.00, + "lon": 40.71 + } +} + +PUT testindex1/_doc/2 +{ + "point": { + "lat": 72.64, + "lon": 22.62 + } +} + +PUT testindex1/_doc/3 +{ + "point": { + "lat": 75.00, + "lon": 28.00 + } +} +``` + +Search for all documents and filter those documents whose points lie within the rectangle defined in the query: + +```json +GET testindex1/_search +{ + "query": { + "bool": { + "must": { + "match_all": {} + }, + "filter": { + "geo_bounding_box": { + "point": { + "top_left": { + "lat": 75, + "lon": 28 + }, + "bottom_right": { + "lat": 73, + "lon": 41 + } + } + } + } + } + } +} +``` + +The response contains the matching document: + +```json +{ + "took" : 20, + "timed_out" : false, + "_shards" : { + "total" : 1, + "successful" : 1, + "skipped" : 0, + "failed" : 0 + }, + "hits" : { + "total" : { + "value" : 1, + "relation" : "eq" + }, + "max_score" : 1.0, + "hits" : [ + { + "_index" : "testindex1", + "_id" : "1", + "_score" : 1.0, + "_source" : { + "point" : { + "lat" : 74.0, + "lon" : 40.71 + } + } + } + ] + } +} +``` + +The preceding response does not include document 3 with a geopoint of `"lat": 75.00, "lon": 28.00` because of the geopoint's limited [precision](#precision). +{: .note} + +## Precision + +Geopoint coordinates are always rounded down at index time. At query time, the bounding box upper boundaries are rounded down, and the lower boundaries are rounded up. Therefore, the documents with geopoints that lie on the lower and left edges of the bounding box might not be included in the results due to rounding error. On the other hand, geopoints that lie on the upper and right edges of the bounding box might be included in the results even though they are outside the boundaries. The rounding error is less than 4.20 × 10−8 degrees for latitude and less than 8.39 × 10−8 degrees for longitude (around 1 cm). + +## Specifying the bounding box + +You can specify the bounding box by providing any of the following combinations of its vertex coordinates: + +- `top_left` and `bottom_right` +- `top_right` and `bottom_left` +- `top`, `left`, `bottom`, and `right` + +The following example specifies the bounding box using the `top`, `left`, `bottom`, and `right` coordinates: + +```json +GET testindex1/_search +{ + "query": { + "bool": { + "must": { + "match_all": {} + }, + "filter": { + "geo_bounding_box": { + "point": { + "top": 75, + "left": 28, + "bottom": 73, + "right": 41 + } + } + } + } + } +} +``` + +## Request fields + +Geo-bounding box queries accept the following fields. + +Field | Data type | Description +:--- | :--- | :--- +_name | String | The name of the filter. Optional. +validation_method | String | The validation method. Valid values are `IGNORE_MALFORMED` (accept geopoints with invalid coordinates), `COERCE` (try to coerce coordinates to valid values), and `STRICT` (return an error when coordinates are invalid). Default is `STRICT`. +type | String | Specifies how to execute the filter. Valid values are `indexed` (index the filter) and `memory` (execute the filter in memory). Default is `memory`. +ignore_unmapped | Boolean | Specifies whether to ignore an unmapped field. If set to `true`, the query does not return any documents that have an unmapped field. If set to `false`, an exception is thrown when the field is unmapped. Default is `false`. + +## Accepted formats + +You can specify coordinates of the bounding box vertices in any [format]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) that geopoint accepts. + +### Using geohash to specify the bounding box + +If you use a geohash to specify the bounding box, the geohash is treated as a rectangle. The upper left vertex of the bounding box corresponds to the upper left vertex of the `top_left` geohash, and the lower right vertex of the bounding box corresponds to the lower right vertex of the `bottom_right` geohash. To specify the bounding box that covers the whole area of a geohash, provide that geohash as both `top_left` and `bottom_right` parameters of the bounding box. \ No newline at end of file diff --git a/_opensearch/supported-field-types/geo-point.md b/_opensearch/supported-field-types/geo-point.md index 8f9866a0475..99c91c5445d 100644 --- a/_opensearch/supported-field-types/geo-point.md +++ b/_opensearch/supported-field-types/geo-point.md @@ -88,6 +88,7 @@ PUT testindex1/_doc/6 "point": { "type": "Point", "coordinates": [74.00, 40.71] + } } ``` From 7442deaa30f3e5a62467f9b9dc52f59286d0f74c Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 5 Dec 2022 17:00:43 -0500 Subject: [PATCH 2/5] Removed geoshape Signed-off-by: Fanit Kolchina --- _opensearch/query-dsl/geo-bounding-box.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/_opensearch/query-dsl/geo-bounding-box.md b/_opensearch/query-dsl/geo-bounding-box.md index 45829a12852..e5c9c69b9fd 100644 --- a/_opensearch/query-dsl/geo-bounding-box.md +++ b/_opensearch/query-dsl/geo-bounding-box.md @@ -22,9 +22,6 @@ PUT testindex1 "properties": { "point": { "type": "geo_point" - }, - "shape": { - "type": "geo_shape" } } } From 7883266315ca3f472fe3e42cc6673f1c33193b16 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 5 Dec 2022 17:08:28 -0500 Subject: [PATCH 3/5] Added geohash examples Signed-off-by: Fanit Kolchina --- _opensearch/query-dsl/geo-bounding-box.md | 48 ++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/_opensearch/query-dsl/geo-bounding-box.md b/_opensearch/query-dsl/geo-bounding-box.md index e5c9c69b9fd..c734625e6d8 100644 --- a/_opensearch/query-dsl/geo-bounding-box.md +++ b/_opensearch/query-dsl/geo-bounding-box.md @@ -177,4 +177,50 @@ You can specify coordinates of the bounding box vertices in any [format]({{site. ### Using geohash to specify the bounding box -If you use a geohash to specify the bounding box, the geohash is treated as a rectangle. The upper left vertex of the bounding box corresponds to the upper left vertex of the `top_left` geohash, and the lower right vertex of the bounding box corresponds to the lower right vertex of the `bottom_right` geohash. To specify the bounding box that covers the whole area of a geohash, provide that geohash as both `top_left` and `bottom_right` parameters of the bounding box. \ No newline at end of file +If you use a geohash to specify the bounding box, the geohash is treated as a rectangle. The upper left vertex of the bounding box corresponds to the upper left vertex of the `top_left` geohash, and the lower right vertex of the bounding box corresponds to the lower right vertex of the `bottom_right` geohash. + +The following example uses a geohash to specify the same bounding box as the previous examples: + +```json +GET testindex1/_search +{ + "query": { + "bool": { + "must": { + "match_all": {} + }, + "filter": { + "geo_bounding_box": { + "point": { + "top_left": "ut7ftjkfxm34", + "bottom_right": "uuvpkcprc4rc" + } + } + } + } + } +} +``` + +To specify the bounding box that covers the whole area of a geohash, provide that geohash as both `top_left` and `bottom_right` parameters of the bounding box: + +```json +GET testindex1/_search +{ + "query": { + "bool": { + "must": { + "match_all": {} + }, + "filter": { + "geo_bounding_box": { + "point": { + "top_left": "ut", + "bottom_right": "ut" + } + } + } + } + } +} +``` \ No newline at end of file From b99feea2aeedfe6d780f9d748290296d8e4dfca5 Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Mon, 5 Dec 2022 20:39:43 -0500 Subject: [PATCH 4/5] Incorporated doc review comments Signed-off-by: Fanit Kolchina --- _opensearch/query-dsl/geo-bounding-box.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_opensearch/query-dsl/geo-bounding-box.md b/_opensearch/query-dsl/geo-bounding-box.md index c734625e6d8..6fdf1f31009 100644 --- a/_opensearch/query-dsl/geo-bounding-box.md +++ b/_opensearch/query-dsl/geo-bounding-box.md @@ -13,7 +13,7 @@ To search for documents that contain [geopoint]({{site.url}}{{site.baseurl}}/ope You can use a geo-bounding box query to search for documents that contain geopoints. -Create a mapping with the `point` field is mapped as `geo_point`: +Create a mapping with the `point` field mapped as `geo_point`: ```json PUT testindex1 @@ -120,7 +120,7 @@ The response contains the matching document: } ``` -The preceding response does not include document 3 with a geopoint of `"lat": 75.00, "lon": 28.00` because of the geopoint's limited [precision](#precision). +The preceding response does not include the document with a geopoint of `"lat": 75.00, "lon": 28.00` because of the geopoint's limited [precision](#precision). {: .note} ## Precision From 79dbec824f23024f6d3120056e95eaadc9988c5c Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Wed, 7 Dec 2022 11:03:15 -0500 Subject: [PATCH 5/5] Implemented editorial feedback Signed-off-by: Fanit Kolchina --- _opensearch/query-dsl/geo-bounding-box.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/_opensearch/query-dsl/geo-bounding-box.md b/_opensearch/query-dsl/geo-bounding-box.md index 6fdf1f31009..8d44eb6d5f2 100644 --- a/_opensearch/query-dsl/geo-bounding-box.md +++ b/_opensearch/query-dsl/geo-bounding-box.md @@ -56,7 +56,7 @@ PUT testindex1/_doc/3 } ``` -Search for all documents and filter those documents whose points lie within the rectangle defined in the query: +Search for all documents and filter the documents whose points lie within the rectangle defined in the query: ```json GET testindex1/_search @@ -125,7 +125,7 @@ The preceding response does not include the document with a geopoint of `"lat": ## Precision -Geopoint coordinates are always rounded down at index time. At query time, the bounding box upper boundaries are rounded down, and the lower boundaries are rounded up. Therefore, the documents with geopoints that lie on the lower and left edges of the bounding box might not be included in the results due to rounding error. On the other hand, geopoints that lie on the upper and right edges of the bounding box might be included in the results even though they are outside the boundaries. The rounding error is less than 4.20 × 10−8 degrees for latitude and less than 8.39 × 10−8 degrees for longitude (around 1 cm). +Geopoint coordinates are always rounded down at index time. At query time, the upper boundaries of the bounding box are rounded down, and the lower boundaries are rounded up. Therefore, the documents with geopoints that lie on the lower and left edges of the bounding box might not be included in the results due to rounding error. On the other hand, geopoints that lie on the upper and right edges of the bounding box might be included in the results even though they are outside the boundaries. The rounding error is less than 4.20 × 10−8 degrees for latitude and less than 8.39 × 10−8 degrees for longitude (around 1 cm). ## Specifying the bounding box @@ -135,7 +135,7 @@ You can specify the bounding box by providing any of the following combinations - `top_right` and `bottom_left` - `top`, `left`, `bottom`, and `right` -The following example specifies the bounding box using the `top`, `left`, `bottom`, and `right` coordinates: +The following example shows how to specify the bounding box using the `top`, `left`, `bottom`, and `right` coordinates: ```json GET testindex1/_search @@ -173,13 +173,13 @@ ignore_unmapped | Boolean | Specifies whether to ignore an unmapped field. If se ## Accepted formats -You can specify coordinates of the bounding box vertices in any [format]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) that geopoint accepts. +You can specify coordinates of the bounding box vertices in any [format]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) that the geopoint field type accepts. -### Using geohash to specify the bounding box +### Using a geohash to specify the bounding box -If you use a geohash to specify the bounding box, the geohash is treated as a rectangle. The upper left vertex of the bounding box corresponds to the upper left vertex of the `top_left` geohash, and the lower right vertex of the bounding box corresponds to the lower right vertex of the `bottom_right` geohash. +If you use a geohash to specify the bounding box, the geohash is treated as a rectangle. The upper-left vertex of the bounding box corresponds to the upper-left vertex of the `top_left` geohash, and the lower-right vertex of the bounding box corresponds to the lower-right vertex of the `bottom_right` geohash. -The following example uses a geohash to specify the same bounding box as the previous examples: +The following example shows how to use a geohash to specify the same bounding box as the previous examples: ```json GET testindex1/_search @@ -202,7 +202,7 @@ GET testindex1/_search } ``` -To specify the bounding box that covers the whole area of a geohash, provide that geohash as both `top_left` and `bottom_right` parameters of the bounding box: +To specify a bounding box that covers the whole area of a geohash, provide that geohash as both `top_left` and `bottom_right` parameters of the bounding box: ```json GET testindex1/_search