Adds geo-bounding box query documentation #2134

kolchfa-aws · 2022-12-05T21:49:41Z

Checklist

[ x] By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

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

VijayanB · 2022-12-05T22:00:33Z

_opensearch/query-dsl/geo-bounding-box.md

+
+### 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.


Shall we add an example for geo_hash?

Added two examples in this section.

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

VijayanB · 2022-12-05T22:01:37Z

Overall looks good. one minor comment, shall we rename geopoint to geo_point wherever it is mentioned as field type.

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

kolchfa-aws · 2022-12-05T22:12:27Z

@VijayanB Thank you so much for the review! I added geohash examples. As for the field name, we refer to geopoints and geoshapes as one word without underscores (https://opensearch.org/docs/latest/opensearch/supported-field-types/geographic/).

carolxob

LGTM.

cwillum · 2022-12-05T22:43:43Z

_opensearch/query-dsl/geo-bounding-box.md

+
+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 where the point field is mapped as geo_point:"
Or,
"Create a mapping with the point field mapped as geo_point:"

cwillum · 2022-12-05T22:50:15Z

_opensearch/query-dsl/geo-bounding-box.md

+}
+```
+
+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).


Do you think it's worthwhile adding "... include document 3 (_doc/3) with a geopoint of ..." ?
Or, even just say "document #3"
It may not be necessary. But it took me a second to understand what that referred to.

I'll change to "the document with a geopoint...". The id is not too relevant.

cwillum · 2022-12-05T22:52:46Z

_opensearch/query-dsl/geo-bounding-box.md

+
+## 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 &times; 10<sup>&minus;8</sup> degrees for latitude and less than 8.39 &times; 10<sup>&minus;8</sup> degrees for longitude (around 1 cm). 


"... due to a rounding error."

"due to rounding error" is a common phrase in computer science that usually doesn't have an article. Let's ask @natebower's opinion.

Based on a little searching, it looks like "rounding error" refers to the concept, so "due to rounding error" is correct.

cwillum

LGTM (with comments).

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

natebower

@kolchfa-aws Please see my comments and changes and let me know if you have any questions. Thanks!

natebower · 2022-12-07T15:02:05Z

_opensearch/query-dsl/geo-bounding-box.md

+}
+```
+
+Search for all documents and filter those documents whose points lie within the rectangle defined in the query:


Could "those" be "the"?

natebower · 2022-12-07T15:11:15Z

_opensearch/query-dsl/geo-bounding-box.md

+
+## 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 &times; 10<sup>&minus;8</sup> degrees for latitude and less than 8.39 &times; 10<sup>&minus;8</sup> degrees for longitude (around 1 cm). 


"the upper boundaries of the bounding box"?

natebower · 2022-12-07T15:12:50Z

_opensearch/query-dsl/geo-bounding-box.md

+
+## 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 &times; 10<sup>&minus;8</sup> degrees for latitude and less than 8.39 &times; 10<sup>&minus;8</sup> degrees for longitude (around 1 cm). 


Based on a little searching, it looks like "rounding error" refers to the concept, so "due to rounding error" is correct.

natebower · 2022-12-07T15:15:37Z

_opensearch/query-dsl/geo-bounding-box.md

+- `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 example doesn't itself specify the bounding box. "The following example shows how to specify the bounding box"?

natebower · 2022-12-07T15:18:12Z

_opensearch/query-dsl/geo-bounding-box.md

+:--- | :--- | :--- 
+_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`.


Change "execute" to "run" or "apply" (or another appropriate verb).

I think "execute" is the best verb here. Will keep it for clarity.

natebower · 2022-12-07T15:21:40Z

_opensearch/query-dsl/geo-bounding-box.md

+
+## 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.  


The end of this sentence makes it sound as though "geopoint" is a proper noun. My brain wants it to be "that accepts geopoints." Can we revise for clarity?

natebower · 2022-12-07T15:22:14Z

_opensearch/query-dsl/geo-bounding-box.md

+
+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


"Using a geohash" (to match the following sentence)?

natebower · 2022-12-07T15:23:19Z

_opensearch/query-dsl/geo-bounding-box.md

+
+### 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. 


Suggested change

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.

natebower · 2022-12-07T15:24:40Z

_opensearch/query-dsl/geo-bounding-box.md

+
+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:


Suggested change

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 in the previous examples:

natebower · 2022-12-07T15:25:54Z

_opensearch/query-dsl/geo-bounding-box.md

+}
+```
+
+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"? "the" is correct if there is just one preexisting bounding box that covers the whole area.

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

opensearch-trigger-bot · 2022-12-07T16:07:21Z

The backport to 1.3 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-1.3 1.3
# Navigate to the new working tree
cd .worktrees/backport-1.3
# Create a new branch
git switch --create backport/backport-2134-to-1.3
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 57c4683ce1e05747088fff980e4d6b3dae250fe3
# Push it to GitHub
git push --set-upstream origin backport/backport-2134-to-1.3
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-1.3

Then, create a pull request where the base branch is 1.3 and the compare/head branch is backport/backport-2134-to-1.3.

opensearch-trigger-bot · 2022-12-07T16:07:23Z

The backport to 2.0 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-2.0 2.0
# Navigate to the new working tree
cd .worktrees/backport-2.0
# Create a new branch
git switch --create backport/backport-2134-to-2.0
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 57c4683ce1e05747088fff980e4d6b3dae250fe3
# Push it to GitHub
git push --set-upstream origin backport/backport-2134-to-2.0
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-2.0

Then, create a pull request where the base branch is 2.0 and the compare/head branch is backport/backport-2134-to-2.0.

opensearch-trigger-bot · 2022-12-07T16:07:24Z

The backport to 2.1 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-2.1 2.1
# Navigate to the new working tree
cd .worktrees/backport-2.1
# Create a new branch
git switch --create backport/backport-2134-to-2.1
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 57c4683ce1e05747088fff980e4d6b3dae250fe3
# Push it to GitHub
git push --set-upstream origin backport/backport-2134-to-2.1
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-2.1

Then, create a pull request where the base branch is 2.1 and the compare/head branch is backport/backport-2134-to-2.1.

opensearch-trigger-bot · 2022-12-07T16:07:24Z

The backport to 2.2 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-2.2 2.2
# Navigate to the new working tree
cd .worktrees/backport-2.2
# Create a new branch
git switch --create backport/backport-2134-to-2.2
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 57c4683ce1e05747088fff980e4d6b3dae250fe3
# Push it to GitHub
git push --set-upstream origin backport/backport-2134-to-2.2
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-2.2

Then, create a pull request where the base branch is 2.2 and the compare/head branch is backport/backport-2134-to-2.2.

opensearch-trigger-bot · 2022-12-07T16:07:25Z

The backport to 2.3 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-2.3 2.3
# Navigate to the new working tree
cd .worktrees/backport-2.3
# Create a new branch
git switch --create backport/backport-2134-to-2.3
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 57c4683ce1e05747088fff980e4d6b3dae250fe3
# Push it to GitHub
git push --set-upstream origin backport/backport-2134-to-2.3
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-2.3

Then, create a pull request where the base branch is 2.3 and the compare/head branch is backport/backport-2134-to-2.3.

* Adds geo-bounding box query documentation Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Removed geoshape Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Added geohash examples Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Incorporated doc review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Implemented editorial feedback Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> (cherry picked from commit 57c4683)

* Adds geo-bounding box query documentation Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Removed geoshape Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Added geohash examples Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Incorporated doc review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Implemented editorial feedback Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> (cherry picked from commit 57c4683) Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

Adds geo-bounding box query documentation

9a69d6a

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

kolchfa-aws self-assigned this Dec 5, 2022

VijayanB reviewed Dec 5, 2022

View reviewed changes

Removed geoshape

7442dea

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

Added geohash examples

7883266

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

carolxob self-requested a review December 5, 2022 22:14

carolxob approved these changes Dec 5, 2022

View reviewed changes

kolchfa-aws marked this pull request as ready for review December 5, 2022 22:23

kolchfa-aws requested a review from a team as a code owner December 5, 2022 22:23

cwillum reviewed Dec 5, 2022

View reviewed changes

cwillum approved these changes Dec 5, 2022

View reviewed changes

Incorporated doc review comments

b99feea

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

VijayanB approved these changes Dec 7, 2022

View reviewed changes

natebower reviewed Dec 7, 2022

View reviewed changes

Implemented editorial feedback

79dbec8

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

kolchfa-aws added backport 1.3 PR: Backport label for v1.3.x backport 2.0 PR: Backport label for v2.0.x backport 2.1 PR: Backport label for 2.1 backport 2.2 PR: Backport label for 2.2 backport 2.3 PR: Backport label for 2.3 backport 2.4 PR: Backport label for 2.4 labels Dec 7, 2022

kolchfa-aws merged commit 57c4683 into main Dec 7, 2022

opensearch-trigger-bot bot mentioned this pull request Dec 7, 2022

[Backport 2.4] Adds geo-bounding box query documentation #2142

Merged

Naarcha-AWS deleted the Fix1815-geo-bounding-box-query branch March 28, 2024 23:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adds geo-bounding box query documentation #2134

Adds geo-bounding box query documentation #2134

kolchfa-aws commented Dec 5, 2022

VijayanB Dec 5, 2022

kolchfa-aws Dec 5, 2022

VijayanB commented Dec 5, 2022

kolchfa-aws commented Dec 5, 2022

carolxob left a comment

cwillum Dec 5, 2022

cwillum Dec 5, 2022

kolchfa-aws Dec 6, 2022

cwillum Dec 5, 2022

kolchfa-aws Dec 6, 2022

natebower Dec 7, 2022

cwillum left a comment

natebower left a comment

natebower Dec 7, 2022

natebower Dec 7, 2022

natebower Dec 7, 2022

natebower Dec 7, 2022

natebower Dec 7, 2022

kolchfa-aws Dec 7, 2022

natebower Dec 7, 2022

kolchfa-aws Dec 7, 2022

natebower Dec 7, 2022

natebower Dec 7, 2022

natebower Dec 7, 2022

natebower Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022


		### 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.


		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`:


		## 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<sup>−8</sup> degrees for latitude and less than 8.39 × 10<sup>−8</sup> degrees for longitude (around 1 cm).


		## 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.


		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 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 in the previous examples:

Adds geo-bounding box query documentation #2134

Adds geo-bounding box query documentation #2134

Conversation

kolchfa-aws commented Dec 5, 2022

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VijayanB commented Dec 5, 2022

kolchfa-aws commented Dec 5, 2022

carolxob left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cwillum left a comment

Choose a reason for hiding this comment

natebower left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

opensearch-trigger-bot bot commented Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022

opensearch-trigger-bot bot commented Dec 7, 2022