diff --git a/_opensearch/query-dsl/xy.md b/_opensearch/query-dsl/xy.md new file mode 100644 index 00000000..bf0bb8b9 --- /dev/null +++ b/_opensearch/query-dsl/xy.md @@ -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. + +xy shape query + + +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. + +xy point query + +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" + } + } + ] + } +} +``` \ No newline at end of file diff --git a/_opensearch/supported-field-types/geo-shape.md b/_opensearch/supported-field-types/geo-shape.md index a6f4c493..2e9cf47e 100644 --- a/_opensearch/supported-field-types/geo-shape.md +++ b/_opensearch/supported-field-types/geo-shape.md @@ -51,7 +51,7 @@ OpenSearch type | GeoJSON type | WKT type | Description [`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 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 @@ -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 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 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 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 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 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 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 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 PUT testindex/_doc/4 @@ -345,7 +345,7 @@ PUT testindex/_doc/7 ## 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: diff --git a/_opensearch/supported-field-types/xy-point.md b/_opensearch/supported-field-types/xy-point.md new file mode 100644 index 00000000..bcafa2c3 --- /dev/null +++ b/_opensearch/supported-field-types/xy-point.md @@ -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`. \ No newline at end of file diff --git a/_opensearch/supported-field-types/xy-shape.md b/_opensearch/supported-field-types/xy-shape.md new file mode 100644 index 00000000..510868e7 --- /dev/null +++ b/_opensearch/supported-field-types/xy-shape.md @@ -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-7decimal 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:
1. RIGHT: counterclockwise. Specify RIGHT orientation by using one of the following strings (uppercase or lowercase): `right`, `counterclockwise`, `ccw`.
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.
Default is `RIGHT`. \ No newline at end of file diff --git a/_opensearch/supported-field-types/xy.md b/_opensearch/supported-field-types/xy.md new file mode 100644 index 00000000..79750eef --- /dev/null +++ b/_opensearch/supported-field-types/xy.md @@ -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} \ No newline at end of file diff --git a/images/xy_query.png b/images/xy_query.png new file mode 100644 index 00000000..6888c193 Binary files /dev/null and b/images/xy_query.png differ diff --git a/images/xy_query_point.png b/images/xy_query_point.png new file mode 100644 index 00000000..dbfc3a9a Binary files /dev/null and b/images/xy_query_point.png differ