Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Backport 2.3] Unify and correct geoshape GeoJSON and WKT examples #7809

Merged
merged 1 commit into from
Jul 23, 2024
Merged

[Backport 2.3] Unify and correct geoshape GeoJSON and WKT examples #7809

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 41 additions & 31 deletions _opensearch/supported-field-types/geo-shape.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ PUT testindex/_doc/1
{
"location" : {
"type" : "point",
"coordinates" : [74.00, 40.71]
"coordinates" : [74.0060, 40.7128]
}
}
```
Expand Down Expand Up @@ -124,10 +124,12 @@ PUT testindex/_doc/3
"location" : {
"type" : "polygon",
"coordinates" : [
[[74.0060, 40.7128],
[71.0589, 42.3601],
[73.7562, 42.6526],
[74.0060, 40.7128]]
[
[74.0060, 40.7128],
[73.7562, 42.6526],
[71.0589, 42.3601],
[74.0060, 40.7128]
]
]
}
}
Expand Down Expand Up @@ -157,15 +159,18 @@ PUT testindex/_doc/4
"location" : {
"type" : "polygon",
"coordinates" : [
[[74.0060, 40.7128],
[71.0589, 42.3601],
[73.7562, 42.6526],
[74.0060, 40.7128]],

[[72.6734,41.7658],
[72.6506, 41.5623],
[73.0515, 41.5582],
[72.6734, 41.7658]]
[
[74.0060, 40.7128],
[73.7562, 42.6526],
[71.0589, 42.3601],
[74.0060, 40.7128]
],
[
[72.6734,41.7658],
[73.0515, 41.5582],
[72.6506, 41.5623],
[72.6734, 41.7658]
]
]
}
}
Expand All @@ -177,12 +182,12 @@ Index a polygon (triangle) with a triangular hole in WKT format:
```json
PUT testindex/_doc/4
{
"location" : "POLYGON ((40.7128 74.0060, 42.3601 71.0589, 42.6526 73.7562, 40.7128 74.0060), (41.7658 72.6734, 41.5623 72.6506, 41.5582 73.0515, 41.7658 72.6734))"
"location" : "POLYGON ((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128), (72.6734 41.7658, 72.6506 41.5623, 73.0515 41.5582, 72.6734 41.7658))"
}
```
{% include copy-curl.html %}

In OpenSearch, you can specify a polygon by listing its vertices clockwise or counterclockwise. This works well for polygons that do not cross the date line (are narrower than 180°). However, a polygon that crosses the date line (is wider than 180°) might be ambiguous because WKT does not impose a specific order on vertices. Thus, you must specify polygons that cross the date line by listing their vertices counterclockwise.
You can specify a polygon in OpenSearch by listing its vertices in clockwise or counterclockwise order. This works well for polygons that do not cross the date line (that are narrower than 180°). However, a polygon that crosses the date line (is wider than 180°) might be ambiguous because WKT does not impose a specific order on vertices. Thus, you must specify polygons that cross the date line by listing their vertices in counterclockwise order.

You can define an [`orientation`](#parameters) parameter to specify the vertex traversal order at mapping time:

Expand Down Expand Up @@ -293,23 +298,28 @@ PUT testindex/_doc/4
"type" : "multipolygon",
"coordinates" : [
[
[[74.0060, 40.7128],
[71.0589, 42.3601],
[73.7562, 42.6526],
[74.0060, 40.7128]],

[[72.6734,41.7658],
[72.6506, 41.5623],
[73.0515, 41.5582],
[72.6734, 41.7658]]
[
[74.0060, 40.7128],
[73.7562, 42.6526],
[71.0589, 42.3601],
[74.0060, 40.7128]
],
[
[73.0515, 41.5582],
[72.6506, 41.5623],
[72.6734, 41.7658],
[73.0515, 41.5582]
]
],
[
[[73.9776, 40.7614],
[73.9554, 40.7827],
[73.9631, 40.7812],
[73.9776, 40.7614]]
[
[73.9146, 40.8252],
[73.8871, 41.0389],
[73.6853, 40.9747],
[73.9146, 40.8252]
]
]
]
}
}
```
Expand All @@ -320,7 +330,7 @@ Index a multi polygon in WKT format:
```json
PUT testindex/_doc/4
{
"location" : "MULTIPOLYGON (((40.7128 74.0060, 42.3601 71.0589, 42.6526 73.7562, 40.7128 74.0060), (41.7658 72.6734, 41.5623 72.6506, 41.5582 73.0515, 41.7658 72.6734)), ((73.9776 40.7614, 73.9554 40.7827, 73.9631 40.7812, 73.9776 40.7614)))"
"location" : "MULTIPOLYGON (((74.0060 40.7128, 71.0589 42.3601, 73.7562 42.6526, 74.0060 40.7128), (72.6734 41.7658, 72.6506 41.5623, 73.0515 41.5582, 72.6734 41.7658)), ((73.9146 40.8252, 73.6853 40.9747, 73.8871 41.0389, 73.9146 40.8252)))"
}
```
{% include copy-curl.html %}
Expand Down Expand Up @@ -398,5 +408,5 @@ Parameter | Description
:--- | :---
`coerce` | A Boolean value that specifies whether to automatically close unclosed linear rings. Default is `false`.
`ignore_malformed` | A Boolean value that specifies to ignore malformed GeoJSON or WKT geoshapes and not to throw an exception. Default is `false` (throw an exception when geoshapes are malformed).
`ignore_z_value` | Specific to points with three coordinates. If `ignore_z_value` is `true`, the third coordinate is not indexed but is still stored in the _source field. If `ignore_z_value` is `false`, an exception is thrown. Default is `true`.
`ignore_z_value` | Specific to points with three coordinates. If `ignore_z_value` is `true`, then the third coordinate is not indexed but is still stored in the `_source` field. If `ignore_z_value` is `false`, then an exception is thrown. Default is `true`.
`orientation` | Specifies the traversal order of the vertices in the geoshape's list of coordinates. `orientation` takes the following values: <br> 1. RIGHT: counterclockwise. Specify RIGHT orientation by using one of the following strings (uppercase or lowercase): `right`, `counterclockwise`, `ccw`. <br> 2. LEFT: clockwise. Specify LEFT orientation by using one of the following strings (uppercase or lowercase): `left`, `clockwise`, `cw`. This value can be overridden by individual documents.<br> Default is `RIGHT`.
Loading