Adds xy point and shape documentation (#1564)
* Adds xy point and shape documentation Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Moved the github link Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Adds documentation for cartesian shapes Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Updated BBOX coordinates Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Fixed typo Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Updated links and GeoJSON Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Incorporated doc review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * One more doc review comment Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Incorporated editorial comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
This commit is contained in:
kolchfa-aws
GitHub
parent
f3a909db20
commit
9122bbb108
|
|
@ -0,0 +1,434 @@
|
||||||
|
---
|
||||||
|
layout: default
|
||||||
|
title: xy queries
|
||||||
|
parent: Query DSL
|
||||||
|
nav_order: 65
|
||||||
|
---
|
||||||
|
|
||||||
|
# xy queries
|
||||||
|
|
||||||
|
To search for documents that contain [xy point]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy-point) and [xy shape]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy-shape) fields, use an xy query.
|
||||||
|
|
||||||
|
## Spatial relations
|
||||||
|
|
||||||
|
When you provide an xy shape to the xy query, the xy fields are matched using the following spatial relations to the provided shape.
|
||||||
|
|
||||||
|
Relation | Description | Supporting xy Field Type
|
||||||
|
:--- | :--- | :---
|
||||||
|
`INTERSECTS` | (Default) Matches documents whose xy point or xy shape intersects the shape provided in the query. | `xy_point`, `xy_shape`
|
||||||
|
`DISJOINT` | Matches documents whose xy shape does not intersect with the shape provided in the query. | `xy_shape`
|
||||||
|
`WITHIN` | Matches documents whose xy shape is completely within the shape provided in the query. | `xy_shape`
|
||||||
|
`CONTAINS` | Matches documents whose xy shape completely contains the shape provided in the query. | `xy_shape`
|
||||||
|
|
||||||
|
The following examples illustrate searching for documents that contain xy shapes. To learn how to search for documents that contain xy points, see the [Querying xy points](#querying-xy-points) section.
|
||||||
|
|
||||||
|
## Defining the shape in an xy query
|
||||||
|
|
||||||
|
You can define the shape in an xy query either by providing a new shape definition at query time or by referencing the name of a shape pre-indexed in another index.
|
||||||
|
|
||||||
|
### Using a new shape definition
|
||||||
|
|
||||||
|
To provide a new shape to an xy query, define it in the `xy_shape` field.
|
||||||
|
|
||||||
|
The following example illustrates searching for documents with xy shapes that match an xy shape defined at query time.
|
||||||
|
|
||||||
|
First, create an index and map the `geometry` field as an `xy_shape`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex
|
||||||
|
{
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"geometry": {
|
||||||
|
"type": "xy_shape"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a document with a point and a document with a polygon:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/1
|
||||||
|
{
|
||||||
|
"geometry": {
|
||||||
|
"type": "point",
|
||||||
|
"coordinates": [0.5, 3.0]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
PUT testindex/_doc/2
|
||||||
|
{
|
||||||
|
"geometry" : {
|
||||||
|
"type" : "polygon",
|
||||||
|
"coordinates" : [
|
||||||
|
[[2.5, 6.0],
|
||||||
|
[0.5, 4.5],
|
||||||
|
[1.5, 2.0],
|
||||||
|
[3.5, 3.5],
|
||||||
|
[2.5, 6.0]]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Define an [`envelope`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy-shape#envelope)—a bounding rectangle in the `[[minX, maxY], [maxX, minY]]` format. Search for documents with xy points or shapes that intersect that envelope:
|
||||||
|
|
||||||
|
```json
|
||||||
|
GET testindex/_search
|
||||||
|
{
|
||||||
|
"query": {
|
||||||
|
"xy_shape": {
|
||||||
|
"geometry": {
|
||||||
|
"shape": {
|
||||||
|
"type": "envelope",
|
||||||
|
"coordinates": [ [ 0.0, 6.0], [ 4.0, 2.0] ]
|
||||||
|
},
|
||||||
|
"relation": "WITHIN"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The following image depicts the example. Both the point and the polygon are within the bounding envelope.
|
||||||
|
|
||||||
|
<img src="{{site.url}}{{site.baseurl}}/images/xy_query.png" alt="xy shape query" width="250">
|
||||||
|
|
||||||
|
|
||||||
|
The response contains both documents:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"took" : 363,
|
||||||
|
"timed_out" : false,
|
||||||
|
"_shards" : {
|
||||||
|
"total" : 1,
|
||||||
|
"successful" : 1,
|
||||||
|
"skipped" : 0,
|
||||||
|
"failed" : 0
|
||||||
|
},
|
||||||
|
"hits" : {
|
||||||
|
"total" : {
|
||||||
|
"value" : 2,
|
||||||
|
"relation" : "eq"
|
||||||
|
},
|
||||||
|
"max_score" : 0.0,
|
||||||
|
"hits" : [
|
||||||
|
{
|
||||||
|
"_index" : "testindex",
|
||||||
|
"_id" : "1",
|
||||||
|
"_score" : 0.0,
|
||||||
|
"_source" : {
|
||||||
|
"geometry" : {
|
||||||
|
"type" : "point",
|
||||||
|
"coordinates" : [
|
||||||
|
0.5,
|
||||||
|
3.0
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"_index" : "testindex",
|
||||||
|
"_id" : "2",
|
||||||
|
"_score" : 0.0,
|
||||||
|
"_source" : {
|
||||||
|
"geometry" : {
|
||||||
|
"type" : "polygon",
|
||||||
|
"coordinates" : [
|
||||||
|
[
|
||||||
|
[
|
||||||
|
2.5,
|
||||||
|
6.0
|
||||||
|
],
|
||||||
|
[
|
||||||
|
0.5,
|
||||||
|
4.5
|
||||||
|
],
|
||||||
|
[
|
||||||
|
1.5,
|
||||||
|
2.0
|
||||||
|
],
|
||||||
|
[
|
||||||
|
3.5,
|
||||||
|
3.5
|
||||||
|
],
|
||||||
|
[
|
||||||
|
2.5,
|
||||||
|
6.0
|
||||||
|
]
|
||||||
|
]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using a pre-indexed shape definition
|
||||||
|
|
||||||
|
When constructing an xy query, you can also reference the name of a shape pre-indexed in another index. Using this method, you can define an xy shape at index time and refer to it by name, providing the following parameters in the `indexed_shape` object.
|
||||||
|
|
||||||
|
Parameter | Description
|
||||||
|
:--- | :---
|
||||||
|
index | The name of the index that contains the pre-indexed shape.
|
||||||
|
id | The document ID of the document that contains the pre-indexed shape.
|
||||||
|
path | The field name of the field that contains the pre-indexed shape as a path.
|
||||||
|
|
||||||
|
The following example illustrates referencing the name of a shape pre-indexed in another index. In this example, the index `pre-indexed-shapes` contains the shape that defines the boundaries, and the index `testindex` contains the shapes whose locations are checked against those boundaries.
|
||||||
|
|
||||||
|
First, create an index `pre-indexed-shapes` and map the `geometry` field for this index as an `xy_shape`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT pre-indexed-shapes
|
||||||
|
{
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"geometry": {
|
||||||
|
"type": "xy_shape"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index an envelope that specifies the boundaries and name it `rectangle`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT pre-indexed-shapes/_doc/rectangle
|
||||||
|
{
|
||||||
|
"geometry": {
|
||||||
|
"type": "envelope",
|
||||||
|
"coordinates" : [ [ 0.0, 6.0], [ 4.0, 2.0] ]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a document with a point and a document with a polygon into the index `testindex`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/1
|
||||||
|
{
|
||||||
|
"geometry": {
|
||||||
|
"type": "point",
|
||||||
|
"coordinates": [0.5, 3.0]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
PUT testindex/_doc/2
|
||||||
|
{
|
||||||
|
"geometry" : {
|
||||||
|
"type" : "polygon",
|
||||||
|
"coordinates" : [
|
||||||
|
[[2.5, 6.0],
|
||||||
|
[0.5, 4.5],
|
||||||
|
[1.5, 2.0],
|
||||||
|
[3.5, 3.5],
|
||||||
|
[2.5, 6.0]]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Search for documents with shapes that intersect `rectangle` in the index `testindex` using a filter:
|
||||||
|
|
||||||
|
```json
|
||||||
|
GET testindex/_search
|
||||||
|
{
|
||||||
|
"query": {
|
||||||
|
"bool": {
|
||||||
|
"filter": {
|
||||||
|
"xy_shape": {
|
||||||
|
"geometry": {
|
||||||
|
"indexed_shape": {
|
||||||
|
"index": "pre-indexed-shapes",
|
||||||
|
"id": "rectangle",
|
||||||
|
"path": "geometry"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The preceding query uses the default spatial relation `INTERSECTS` and returns both the point and the polygon:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"took" : 26,
|
||||||
|
"timed_out" : false,
|
||||||
|
"_shards" : {
|
||||||
|
"total" : 1,
|
||||||
|
"successful" : 1,
|
||||||
|
"skipped" : 0,
|
||||||
|
"failed" : 0
|
||||||
|
},
|
||||||
|
"hits" : {
|
||||||
|
"total" : {
|
||||||
|
"value" : 2,
|
||||||
|
"relation" : "eq"
|
||||||
|
},
|
||||||
|
"max_score" : 0.0,
|
||||||
|
"hits" : [
|
||||||
|
{
|
||||||
|
"_index" : "testindex",
|
||||||
|
"_id" : "1",
|
||||||
|
"_score" : 0.0,
|
||||||
|
"_source" : {
|
||||||
|
"geometry" : {
|
||||||
|
"type" : "point",
|
||||||
|
"coordinates" : [
|
||||||
|
0.5,
|
||||||
|
3.0
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"_index" : "testindex",
|
||||||
|
"_id" : "2",
|
||||||
|
"_score" : 0.0,
|
||||||
|
"_source" : {
|
||||||
|
"geometry" : {
|
||||||
|
"type" : "polygon",
|
||||||
|
"coordinates" : [
|
||||||
|
[
|
||||||
|
[
|
||||||
|
2.5,
|
||||||
|
6.0
|
||||||
|
],
|
||||||
|
[
|
||||||
|
0.5,
|
||||||
|
4.5
|
||||||
|
],
|
||||||
|
[
|
||||||
|
1.5,
|
||||||
|
2.0
|
||||||
|
],
|
||||||
|
[
|
||||||
|
3.5,
|
||||||
|
3.5
|
||||||
|
],
|
||||||
|
[
|
||||||
|
2.5,
|
||||||
|
6.0
|
||||||
|
]
|
||||||
|
]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Querying xy points
|
||||||
|
|
||||||
|
You can also use an xy query to search for documents that contain xy points.
|
||||||
|
|
||||||
|
Create a mapping with `point` as `xy_point`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex1
|
||||||
|
{
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"point": {
|
||||||
|
"type": "xy_point"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index three points:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex1/_doc/1
|
||||||
|
{
|
||||||
|
"point": "1.0, 1.0"
|
||||||
|
}
|
||||||
|
|
||||||
|
PUT testindex1/_doc/2
|
||||||
|
{
|
||||||
|
"point": "2.0, 0.0"
|
||||||
|
}
|
||||||
|
|
||||||
|
PUT testindex1/_doc/3
|
||||||
|
{
|
||||||
|
"point": "-2.0, 2.0"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Search for points that lie within the circle with the center at (0, 0) and a radius of 2:
|
||||||
|
|
||||||
|
```json
|
||||||
|
GET testindex1/_search
|
||||||
|
{
|
||||||
|
"query": {
|
||||||
|
"xy_shape": {
|
||||||
|
"point": {
|
||||||
|
"shape": {
|
||||||
|
"type": "circle",
|
||||||
|
"coordinates": [0.0, 0.0],
|
||||||
|
"radius": 2
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
xy point only supports the default `INTERSECTS` spatial relation, so you don't need to provide the `relation` parameter.
|
||||||
|
{: .note}
|
||||||
|
|
||||||
|
The following image depicts the example. Points 1 and 2 are within the circle, and point 3 is outside the circle.
|
||||||
|
|
||||||
|
<img src="{{site.url}}{{site.baseurl}}/images/xy_query_point.png" alt="xy point query" width="300">
|
||||||
|
|
||||||
|
The response returns documents 1 and 2:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"took" : 575,
|
||||||
|
"timed_out" : false,
|
||||||
|
"_shards" : {
|
||||||
|
"total" : 1,
|
||||||
|
"successful" : 1,
|
||||||
|
"skipped" : 0,
|
||||||
|
"failed" : 0
|
||||||
|
},
|
||||||
|
"hits" : {
|
||||||
|
"total" : {
|
||||||
|
"value" : 2,
|
||||||
|
"relation" : "eq"
|
||||||
|
},
|
||||||
|
"max_score" : 0.0,
|
||||||
|
"hits" : [
|
||||||
|
{
|
||||||
|
"_index" : "testindex1",
|
||||||
|
"_id" : "1",
|
||||||
|
"_score" : 0.0,
|
||||||
|
"_source" : {
|
||||||
|
"point" : "1.0, 1.0"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"_index" : "testindex1",
|
||||||
|
"_id" : "2",
|
||||||
|
"_score" : 0.0,
|
||||||
|
"_source" : {
|
||||||
|
"point" : "2.0, 0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
@ -51,7 +51,7 @@ OpenSearch type | GeoJSON type | WKT type | Description
|
||||||
[`multilinestring`](#multiline-string) | MultiLineString | MULTILINESTRING | An array of linestrings.
|
[`multilinestring`](#multiline-string) | MultiLineString | MULTILINESTRING | An array of linestrings.
|
||||||
[`multipolygon`](#multi-polygon) | MultiPolygon | MULTIPOLYGON | An array of polygons.
|
[`multipolygon`](#multi-polygon) | MultiPolygon | MULTIPOLYGON | An array of polygons.
|
||||||
[`geometrycollection`](#geometry-collection) | GeometryCollection | GEOMETRYCOLLECTION | A collection of geoshapes that may be of different types.
|
[`geometrycollection`](#geometry-collection) | GeometryCollection | GEOMETRYCOLLECTION | A collection of geoshapes that may be of different types.
|
||||||
[`envelope`](#envelope) | N/A | BBOX | A bounding rectangle specified by top-left and bottom-right vertices.
|
[`envelope`](#envelope) | N/A | BBOX | A bounding rectangle specified by upper-left and lower-right vertices.
|
||||||
|
|
||||||
## Point
|
## Point
|
||||||
|
|
||||||
|
|
@ -78,11 +78,11 @@ PUT testindex/_doc/1
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Line string
|
## Linestring
|
||||||
|
|
||||||
A line string is a line specified by two or more points. If the points are collinear, the line string is a straight line. Otherwise, the line string represents a path made of line segments.
|
A linestring is a line specified by two or more points. If the points are collinear, the linestring is a straight line. Otherwise, the linestring represents a path made of line segments.
|
||||||
|
|
||||||
Index a line string in GeoJSON format:
|
Index a linestring in GeoJSON format:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
PUT testindex/_doc/2
|
PUT testindex/_doc/2
|
||||||
|
|
@ -94,7 +94,7 @@ PUT testindex/_doc/2
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Index a line string in WKT format:
|
Index a linestring in WKT format:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
PUT testindex/_doc/2
|
PUT testindex/_doc/2
|
||||||
|
|
@ -208,11 +208,11 @@ PUT testindex/_doc/3
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Multi point
|
## Multipoint
|
||||||
|
|
||||||
A multi point is an array of discrete related points that are not connected.
|
A multipoint is an array of discrete related points that are not connected.
|
||||||
|
|
||||||
Index a multi point in GeoJSON format:
|
Index a multipoint in GeoJSON format:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
PUT testindex/_doc/6
|
PUT testindex/_doc/6
|
||||||
|
|
@ -227,7 +227,7 @@ PUT testindex/_doc/6
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Index a multi point in WKT format:
|
Index a multipoint in WKT format:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
PUT testindex/_doc/6
|
PUT testindex/_doc/6
|
||||||
|
|
@ -236,11 +236,11 @@ PUT testindex/_doc/6
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Multiline string
|
## Multilinestring
|
||||||
|
|
||||||
A multiline string is an array of line strings.
|
A multilinestring is an array of linestrings.
|
||||||
|
|
||||||
Index a line string in GeoJSON format:
|
Index a linestring in GeoJSON format:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
PUT testindex/_doc/2
|
PUT testindex/_doc/2
|
||||||
|
|
@ -255,7 +255,7 @@ PUT testindex/_doc/2
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Index a line string in WKT format:
|
Index a linestring in WKT format:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
PUT testindex/_doc/2
|
PUT testindex/_doc/2
|
||||||
|
|
@ -264,11 +264,11 @@ PUT testindex/_doc/2
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Multi polygon
|
## Multipolygon
|
||||||
|
|
||||||
A multi polygon is an array of polygons. In this example, the first polygon contains a hole, and the second does not.
|
A multipolygon is an array of polygons. In this example, the first polygon contains a hole, and the second does not.
|
||||||
|
|
||||||
Index a multi polygon in GeoJSON format:
|
Index a multipolygon in GeoJSON format:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
PUT testindex/_doc/4
|
PUT testindex/_doc/4
|
||||||
|
|
@ -298,7 +298,7 @@ PUT testindex/_doc/4
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Index a multi polygon in WKT format:
|
Index a multipolygon in WKT format:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
PUT testindex/_doc/4
|
PUT testindex/_doc/4
|
||||||
|
|
@ -345,7 +345,7 @@ PUT testindex/_doc/7
|
||||||
|
|
||||||
## Envelope
|
## Envelope
|
||||||
|
|
||||||
An envelope is a bounding rectangle specified by top-left and bottom-right vertices. The GeoJSON format is `[[minLon, maxLat], [maxLon, minLat]]`.
|
An envelope is a bounding rectangle specified by upper-left and lower-right vertices. The GeoJSON format is `[[minLon, maxLat], [maxLon, minLat]]`.
|
||||||
|
|
||||||
Index an envelope in GeoJSON format:
|
Index an envelope in GeoJSON format:
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,97 @@
|
||||||
|
---
|
||||||
|
layout: default
|
||||||
|
title: xy point
|
||||||
|
nav_order: 58
|
||||||
|
has_children: false
|
||||||
|
parent: Cartesian field types
|
||||||
|
grand_parent: Supported field types
|
||||||
|
---
|
||||||
|
|
||||||
|
# xy point field type
|
||||||
|
|
||||||
|
An xy point field type contains a point in a two-dimensional Cartesian coordinate system, specified by x and y coordinates. It is based on the Lucene [XYPoint](https://lucene.apache.org/core/9_3_0/core/org/apache/lucene/geo/XYPoint.html) field type. The xy point field type is similar to the [geopoint]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) field type, but does not have the range limitations of geopoint. The coordinates of an xy point are single-precision floating-point values. For information about the range and precision of floating-point values, see [Numeric field types]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/).
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
Create a mapping with an xy point field type:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex1
|
||||||
|
{
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"point": {
|
||||||
|
"type": "xy_point"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Formats
|
||||||
|
|
||||||
|
xy points can be indexed in the following formats:
|
||||||
|
|
||||||
|
- An object with x and y coordinates
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex1/_doc/1
|
||||||
|
{
|
||||||
|
"point": {
|
||||||
|
"x": 0.5,
|
||||||
|
"y": 4.5
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- A string in the "`x`, `y`" format
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex1/_doc/2
|
||||||
|
{
|
||||||
|
"point": "0.5, 4.5"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- An array in the [`x`, `y`] format
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex1/_doc/3
|
||||||
|
{
|
||||||
|
"point": [0.5, 4.5]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- A [well-known text (WKT)](https://docs.opengeospatial.org/is/12-063r5/12-063r5.html) POINT in the "POINT(`x` `y`)" format
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex1/_doc/4
|
||||||
|
{
|
||||||
|
"point": "POINT (0.5 4.5)"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- GeoJSON format
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex1/_doc/5
|
||||||
|
{
|
||||||
|
"point" : {
|
||||||
|
"type" : "Point",
|
||||||
|
"coordinates" : [0.5, 4.5]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
In all xy point formats, the coordinates must be specified in the `x, y` order.
|
||||||
|
{: .note}
|
||||||
|
|
||||||
|
## Parameters
|
||||||
|
|
||||||
|
The following table lists the parameters accepted by xy point field types. All parameters are optional.
|
||||||
|
|
||||||
|
Parameter | Description
|
||||||
|
:--- | :---
|
||||||
|
`ignore_malformed` | A Boolean value that specifies to ignore malformed values and not to throw an exception. Default is `false`.
|
||||||
|
`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.
|
||||||
|
[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. The value must be of the same type as the field. If this parameter is not specified, the field is treated as missing when its value is `null`. Default is `null`.
|
||||||
|
|
@ -0,0 +1,379 @@
|
||||||
|
---
|
||||||
|
layout: default
|
||||||
|
title: xy shape
|
||||||
|
nav_order: 59
|
||||||
|
has_children: false
|
||||||
|
parent: Cartesian field types
|
||||||
|
grand_parent: Supported field types
|
||||||
|
---
|
||||||
|
|
||||||
|
# xy shape field type
|
||||||
|
|
||||||
|
An xy shape field type contains a shape, such as a polygon or a collection of xy points. It is based on the Lucene [XYShape](https://lucene.apache.org/core/9_3_0/core/org/apache/lucene/document/XYShape.html) field type. To index an xy shape, OpenSearch tessellates the shape into a triangular mesh and stores each triangle in a BKD tree (a set of balanced k-dimensional trees). This provides a 10<sup>-7</sup>decimal degree of precision, which represents near-perfect spatial resolution.
|
||||||
|
|
||||||
|
The xy shape field type is similar to the [geoshape]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-shape/) field type, but it represents shapes on the Cartesian plane, which is not based on the Earth-fixed terrestrial reference system. The coordinates of an xy shape are single-precision floating-point values. For information about the range and precision of floating-point values, see [Numeric field types]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/).
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
Create a mapping with an xy shape field type:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex
|
||||||
|
{
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"location": {
|
||||||
|
"type": "xy_shape"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Formats
|
||||||
|
|
||||||
|
xy shapes can be indexed in the following formats:
|
||||||
|
|
||||||
|
- [GeoJSON](https://geojson.org/)
|
||||||
|
- [Well-known text (WKT)](https://docs.opengeospatial.org/is/12-063r5/12-063r5.html)
|
||||||
|
|
||||||
|
In both GeoJSON and WKT, the coordinates must be specified in the `x, y` order within coordinate arrays.
|
||||||
|
{: .note}
|
||||||
|
|
||||||
|
## xy shape types
|
||||||
|
|
||||||
|
The following table describes the possible xy shape types and their relationship to the GeoJSON and WKT types.
|
||||||
|
|
||||||
|
OpenSearch type | GeoJSON type | WKT type | Description
|
||||||
|
:--- | :--- | :--- | :---
|
||||||
|
[`point`](#point) | Point | POINT | A geographic point specified by the x and y coordinates.
|
||||||
|
[`linestring`](#line-string) | LineString | LINESTRING | A line specified by two or more points. May be a straight line or a path of connected line segments.
|
||||||
|
[`polygon`](#polygon) | Polygon | POLYGON | A polygon specified by a list of vertices in coordinate form. The polygon must be closed, meaning the last point must be the same as the first point. Therefore, to create an n-gon, n+1 vertices are required. The minimum number of vertices is four, which creates a triangle.
|
||||||
|
[`multipoint`](#multi-point) | MultiPoint | MULTIPOINT | An array of discrete related points that are not connected.
|
||||||
|
[`multilinestring`](#multiline-string) | MultiLineString | MULTILINESTRING | An array of linestrings.
|
||||||
|
[`multipolygon`](#multi-polygon) | MultiPolygon | MULTIPOLYGON | An array of polygons.
|
||||||
|
[`geometrycollection`](#geometry-collection) | GeometryCollection | GEOMETRYCOLLECTION | A collection of xy shapes that may be of different types.
|
||||||
|
[`envelope`](#envelope) | N/A | BBOX | A bounding rectangle specified by upper-left and lower-right vertices.
|
||||||
|
|
||||||
|
## Point
|
||||||
|
|
||||||
|
A point is specified by a single pair of coordinates.
|
||||||
|
|
||||||
|
Index a point in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/1
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "point",
|
||||||
|
"coordinates" : [0.5, 4.5]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a point in WKT format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/1
|
||||||
|
{
|
||||||
|
"location" : "POINT (0.5 4.5)"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Linestring
|
||||||
|
|
||||||
|
A linestring is a line specified by two or more points. If the points are collinear, the linestring is a straight line. Otherwise, the linestring represents a path made of line segments.
|
||||||
|
|
||||||
|
Index a linestring in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/2
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "linestring",
|
||||||
|
"coordinates" : [[0.5, 4.5], [-1.5, 2.3]]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a linestring in WKT format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/2
|
||||||
|
{
|
||||||
|
"location" : "LINESTRING (0.5 4.5, -1.5 2.3)"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Polygon
|
||||||
|
|
||||||
|
A polygon is specified by a list of vertices in coordinate form. The polygon must be closed, meaning the last point must be the same as the first point. In the following example, a triangle is created using four points.
|
||||||
|
|
||||||
|
GeoJSON requires that you list the vertices of the polygon counterclockwise. WKT does not impose a specific order on vertices.
|
||||||
|
{: .note}
|
||||||
|
|
||||||
|
Index a polygon (triangle) in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/3
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "polygon",
|
||||||
|
"coordinates" : [
|
||||||
|
[[0.5, 4.5],
|
||||||
|
[2.5, 6.0],
|
||||||
|
[1.5, 2.0],
|
||||||
|
[0.5, 4.5]]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a polygon (triangle) in WKT format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/3
|
||||||
|
{
|
||||||
|
"location" : "POLYGON ((0.5 4.5, 2.5 6.0, 1.5 2.0, 0.5 4.5))"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The polygon may have holes inside. In this case, the `coordinates` field will contain multiple arrays. The first array represents the outer polygon, and each subsequent array represents a hole. Holes are represented as polygons and specified as arrays of coordinates.
|
||||||
|
|
||||||
|
GeoJSON requires that you list the vertices of the polygon counterclockwise and the vertices of the hole clockwise. WKT does not impose a specific order on vertices.
|
||||||
|
{: .note}
|
||||||
|
|
||||||
|
Index a polygon (triangle) with a triangular hole in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/4
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "polygon",
|
||||||
|
"coordinates" : [
|
||||||
|
[[0.5, 4.5],
|
||||||
|
[2.5, 6.0],
|
||||||
|
[1.5, 2.0],
|
||||||
|
[0.5, 4.5]],
|
||||||
|
|
||||||
|
[[1.0, 4.5],
|
||||||
|
[1.5, 4.5],
|
||||||
|
[1.5, 4.0],
|
||||||
|
[1.0, 4.5]]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a polygon (triangle) with a triangular hole in WKT format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/4
|
||||||
|
{
|
||||||
|
"location" : "POLYGON ((0.5 4.5, 2.5 6.0, 1.5 2.0, 0.5 4.5), (1.0 4.5, 1.5 4.5, 1.5 4.0, 1.0 4.5))"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
By default, the vertices of the polygon are traversed in a counterclockwise order. You can define an [`orientation`](#parameters) parameter to specify the vertex traversal order at mapping time:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex
|
||||||
|
{
|
||||||
|
"mappings": {
|
||||||
|
"properties": {
|
||||||
|
"location": {
|
||||||
|
"type": "xy_shape",
|
||||||
|
"orientation" : "left"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Subsequently indexed documents can override the `orientation` setting:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/3
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "polygon",
|
||||||
|
"orientation" : "cw",
|
||||||
|
"coordinates" : [
|
||||||
|
[[0.5, 4.5],
|
||||||
|
[2.5, 6.0],
|
||||||
|
[1.5, 2.0],
|
||||||
|
[0.5, 4.5]]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Multipoint
|
||||||
|
|
||||||
|
A multipoint is an array of discrete related points that are not connected.
|
||||||
|
|
||||||
|
Index a multipoint in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/6
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "multipoint",
|
||||||
|
"coordinates" : [
|
||||||
|
[0.5, 4.5],
|
||||||
|
[2.5, 6.0]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a multipoint in WKT format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/6
|
||||||
|
{
|
||||||
|
"location" : "MULTIPOINT (0.5 4.5, 2.5 6.0)"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Multilinestring
|
||||||
|
|
||||||
|
A multilinestring is an array of linestrings.
|
||||||
|
|
||||||
|
Index a multilinestring in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/2
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "multilinestring",
|
||||||
|
"coordinates" : [
|
||||||
|
[[0.5, 4.5], [2.5, 6.0]],
|
||||||
|
[[1.5, 2.0], [3.5, 3.5]]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a linestring in WKT format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/2
|
||||||
|
{
|
||||||
|
"location" : "MULTILINESTRING ((0.5 4.5, 2.5 6.0), (1.5 2.0, 3.5 3.5))"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Multipolygon
|
||||||
|
|
||||||
|
A multipolygon is an array of polygons. In this example, the first polygon contains a hole, and the second does not.
|
||||||
|
|
||||||
|
Index a multipolygon in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/4
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "multipolygon",
|
||||||
|
"coordinates" : [
|
||||||
|
[
|
||||||
|
[[0.5, 4.5],
|
||||||
|
[2.5, 6.0],
|
||||||
|
[1.5, 2.0],
|
||||||
|
[0.5, 4.5]],
|
||||||
|
|
||||||
|
[[1.0, 4.5],
|
||||||
|
[1.5, 4.5],
|
||||||
|
[1.5, 4.0],
|
||||||
|
[1.0, 4.5]]
|
||||||
|
],
|
||||||
|
[
|
||||||
|
[[2.0, 0.0],
|
||||||
|
[1.0, 2.0],
|
||||||
|
[3.0, 1.0],
|
||||||
|
[2.0, 0.0]]
|
||||||
|
]
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a multipolygon in WKT format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/4
|
||||||
|
{
|
||||||
|
"location" : "MULTIPOLYGON (((0.5 4.5, 2.5 6.0, 1.5 2.0, 0.5 4.5), (1.0 4.5, 1.5 4.5, 1.5 4.0, 1.0 4.5)), ((2.0 0.0, 1.0 2.0, 3.0 1.0, 2.0 0.0)))"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Geometry collection
|
||||||
|
|
||||||
|
A geometry collection is a collection of xy shapes that may be of different types.
|
||||||
|
|
||||||
|
Index a geometry collection in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/7
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type": "geometrycollection",
|
||||||
|
"geometries": [
|
||||||
|
{
|
||||||
|
"type": "point",
|
||||||
|
"coordinates": [0.5, 4.5]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"type": "linestring",
|
||||||
|
"coordinates": [[2.5, 6.0], [1.5, 2.0]]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Index a geometry collection in WKT format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/7
|
||||||
|
{
|
||||||
|
"location" : "GEOMETRYCOLLECTION (POINT (0.5 4.5), LINESTRING(2.5 6.0, 1.5 2.0))"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Envelope
|
||||||
|
|
||||||
|
An envelope is a bounding rectangle specified by upper-left and lower-right vertices. The GeoJSON format is `[[minX, maxY], [maxX, minY]]`.
|
||||||
|
|
||||||
|
Index an envelope in GeoJSON format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/2
|
||||||
|
{
|
||||||
|
"location" : {
|
||||||
|
"type" : "envelope",
|
||||||
|
"coordinates" : [[3.0, 2.0], [6.0, 0.0]]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
In WKT format, use `BBOX (minX, maxY, maxX, minY)`.
|
||||||
|
|
||||||
|
Index an envelope in WKT BBOX format:
|
||||||
|
|
||||||
|
```json
|
||||||
|
PUT testindex/_doc/8
|
||||||
|
{
|
||||||
|
"location" : "BBOX (3.0, 2.0, 6.0, 0.0)"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Parameters
|
||||||
|
|
||||||
|
The following table lists the parameters accepted by xy shape field types. All parameters are optional.
|
||||||
|
|
||||||
|
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 xy shapes and not to throw an exception. Default is `false` (throw an exception when xy shapes 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`.
|
||||||
|
`orientation` | Specifies the traversal order of the vertices in the xy shape'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`.
|
||||||
|
|
@ -0,0 +1,26 @@
|
||||||
|
---
|
||||||
|
layout: default
|
||||||
|
title: Cartesian field types
|
||||||
|
nav_order: 57
|
||||||
|
has_children: true
|
||||||
|
has_toc: false
|
||||||
|
parent: Supported field types
|
||||||
|
---
|
||||||
|
|
||||||
|
# Cartesian field types
|
||||||
|
|
||||||
|
Cartesian field types facilitate indexing and searching of points and shapes in a two-dimensional Cartesian coordinate system. Cartesian field types are similar to [geographic]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geographic/) field types, except they represent points and shapes on the Cartesian plane, which is not based on the Earth-fixed terrestrial reference system. Calculating distances on a plane is more efficient than calculating distances on a sphere, so distance sorting is faster for Cartesian field types.
|
||||||
|
|
||||||
|
Cartesian field types work well for spatial applications like virtual reality, computer-aided design (CAD), and amusement park and sporting venue mapping.
|
||||||
|
|
||||||
|
The coordinates for the Cartesian field types are single-precision floating-point values. For information about the range and precision of floating-point values, see [Numeric field types]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/numeric/).
|
||||||
|
|
||||||
|
The following table lists all Cartesian field types that OpenSearch supports.
|
||||||
|
|
||||||
|
Field Data Type | Description
|
||||||
|
:--- | :---
|
||||||
|
[`xy_point`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy-point/) | A point in a two-dimensional Cartesian coordinate system, specified by x and y coordinates.
|
||||||
|
[`xy_shape`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy-shape/) | A shape, such as a polygon or a collection of xy points, in a two-dimensional Cartesian coordinate system.
|
||||||
|
|
||||||
|
Currently, OpenSearch supports indexing and searching of Cartesian field types but not aggregations on Cartesian field types. If you'd like to see aggregations implemented, open a [GitHub issue](https://github.com/opensearch-project/geospatial).
|
||||||
|
{: .note}
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 14 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 13 KiB |
Loading…
Reference in New Issue