Adds xy point and shape documentation #1564

kolchfa-aws · 2022-10-14T13:19:30Z

Fixes #862

Checklist

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 <[email protected]>

kolchfa-aws · 2022-10-27T16:03:44Z

@VijayanB @navneet1v @nandi-github This is the xy point and shape PR. Please review and leave comments if you want anything changed. Thank you!

Signed-off-by: Fanit Kolchina <[email protected]>

navneet1v · 2022-10-27T20:19:09Z

_opensearch/supported-field-types/xy-point.md

+
+# 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/8_5_1/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/).


The link added for lucene is from 8.5 release. Just want to know do we update our links in the documentation to point to the latest version of lucene?

I updated the link to 9.3.0, which is the version of Lucene that OpenSearch uses now. We have not been updating Lucene links in the docs, but we can add this step as part of our release process.

navneet1v · 2022-10-27T20:20:53Z

_opensearch/supported-field-types/xy-shape.md

+
+# 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/8_3_0/sandbox/org/apache/lucene/document/XYShape.html) field type. To index a geoshape, OpenSearch tesselates the shape into a triangular mesh and stores each triangle in a BKD tree. This provides a 10<sup>-7</sup>decimal degree of precision, which represents near-perfect spatial resolution.


the lucene documentation link here is for 8.3.0 but above it is for 8.5.1 should we be consistent here?

I think we can use lucene version that will be part of OpenSearch 2.4. wdyt @navneet1v ?

I updated the link to 9.3.0

VijayanB · 2022-10-27T20:42:09Z

_opensearch/supported-field-types/xy-point.md

+
+- A [Well-Known Text](https://docs.opengeospatial.org/is/12-063r5/12-063r5.html) POINT in the "POINT(`x` `y`)" format
+
+```json


Shall we include xy point as GeoJSON? This feature is available in 2.4 as well.
ex:

{ "point" : { "type" : "Point", "coordinates" : [0.5, 4.5] } }

Added the GeoJSON format.

Signed-off-by: Fanit Kolchina <[email protected]>

naveentatikonda · 2022-10-28T16:32:14Z

_opensearch/supported-field-types/xy-point.md

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


Can you please check if this link is working.
({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/)

I'm getting a 404 error when I'm trying to access it

This is a relative link. It is working, but you cannot access it directly. We have a link checker and I made sure that all links are working as part of the commit.

Got it, Thanks!

vagimeli

Minimal edits. Looks good.

vagimeli · 2022-11-02T14:53:43Z

_opensearch/query-dsl/xy.md

+
+## Spatial relations
+
+When you provide an xy shape to the xy query, the xy fields are matched using following spatial relations to the provided shape:


"using the following..."

vagimeli · 2022-11-02T14:55:29Z

_opensearch/query-dsl/xy.md

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


delete comma after "time"

vagimeli · 2022-11-02T14:58:40Z

_opensearch/query-dsl/xy.md

+}
+```
+
+Define an [`envelope`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy-shape#envelope)&mdash;a bounding rectangle in the `[[minX, maxY], [maxX, minY]]` format. Search for documents with xy points or shapes that intersect that envelope:


Should this text &mdash be here?

this is the code to insert a dash in HTML, but I'm guessing this wasn't intentional?

It is intentional. This is how I render em dashes.

vagimeli · 2022-11-02T15:27:59Z

_opensearch/supported-field-types/xy-shape.md

+
+# 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 tesselates the shape into a triangular mesh and stores each triangle in a BKD tree. This provides a 10<sup>-7</sup>decimal degree of precision, which represents near-perfect spatial resolution.


Follow M-W dictionary spelling "tessellates"

vagimeli · 2022-11-02T15:30:50Z

_opensearch/supported-field-types/xy-shape.md

+
+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 tesselates the shape into a triangular mesh and stores each triangle in a BKD tree. 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/).


Change "floating point values" to "floating-point values"

vagimeli · 2022-11-02T15:46:56Z

_opensearch/supported-field-types/xy-shape.md

+
+A multiline string is an array of line strings.
+
+Index a line string in GeoJSON format:


Should it read "Index a multiline...?"

vagimeli · 2022-11-02T15:47:24Z

_opensearch/supported-field-types/xy-shape.md

+}
+```
+
+Index a line string in WKT format:


Should it read "Index a multiline...?"

vagimeli · 2022-11-02T15:55:38Z

_opensearch/supported-field-types/xy.md

+
+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, CAD, and amusement park and sporting venue mapping. 


"computer-aided design (CAD)"

vagimeli · 2022-11-02T15:56:15Z

_opensearch/supported-field-types/xy.md

+
+Cartesian field types work well for spatial applications like virtual reality, 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/).


"...floating-point values."

vagimeli · 2022-11-02T15:57:59Z

_opensearch/supported-field-types/xy.md

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


Insert comma after "Currently"

ariamarble · 2022-11-02T17:50:38Z

_opensearch/query-dsl/xy.md

+When you provide an xy shape to the xy query, the xy fields are matched using following spatial relations to the provided shape:
+
+Relation | Description | Supporting xy Field Type
+:--- | :--- | :--- | :--- 


Suggested change

:--- | :--- | :--- | :---

:--- | :--- | :---

ariamarble · 2022-11-02T17:59:30Z

_opensearch/query-dsl/xy.md

+}
+```
+
+Search for points that lie within the circle with the center (0, 0) and radius 2:


a radius of ?

ariamarble · 2022-11-02T18:04:38Z

_opensearch/supported-field-types/xy-point.md

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


Suggested change

[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) | A value to be used in place of `null`. 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`.

[`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`.

ariamarble · 2022-11-02T18:12:14Z

_opensearch/supported-field-types/xy-shape.md

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


should it be throws ?

I think it should be "throw" because it's saying the default is to throw an exception. But let's wait for @natebower's review.

They're both technically correct because these sentences are fragments, so they're dependent on omitted text, which could be whatever we want it to be. I vote for "throw" in order to maintain consistency with the preceding sentence.

ariamarble · 2022-11-02T18:15:48Z

_opensearch/supported-field-types/xy.md

+
+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, CAD, and amusement park and sporting venue mapping. 


Suggested change

Cartesian field types work well for spatial applications like virtual reality, CAD, and amusement park and sporting venue mapping.

Cartesian field types work well for spatial applications like virtual reality, computer-aided design (CAD), amusement parks, and sporting venue mapping.

This refers to the mapping of amusement parks and sporting venues. I will ask @natebower.

ariamarble

LGTM other than my comments

Signed-off-by: Fanit Kolchina <[email protected]>

natebower

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

natebower · 2022-11-03T17:06:43Z

_opensearch/query-dsl/xy.md

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


Suggested change

When you provide an xy shape to the xy query, the xy fields are matched using the following spatial relations to the provided shape:

When you provide an xy shape to the xy query, the xy fields are matched using the following spatial relations to the provided shape.

natebower · 2022-11-03T17:09:13Z

_opensearch/query-dsl/xy.md

+`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 examples below 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.


Suggested change

The examples below 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.

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.

natebower · 2022-11-03T17:32:33Z

_opensearch/query-dsl/xy.md

+}
+```
+
+Refer to the following image to visualize the example. Both the point and the polygon are within the bounding envelope:


Can we make the first sentence clearer? "The following image depicts the example"?

natebower · 2022-11-03T17:32:49Z

_opensearch/query-dsl/xy.md

+}
+```
+
+Refer to the following image to visualize the example. Both the point and the polygon are within the bounding envelope:


Suggested change

Refer to the following image to visualize the example. Both the point and the polygon are within the bounding envelope:

Refer to the following image to visualize the example. Both the point and the polygon are within the bounding envelope.

natebower · 2022-11-03T17:41:30Z

_opensearch/query-dsl/xy.md

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


Suggested change

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:

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.

natebower · 2022-11-03T20:02:03Z

_opensearch/supported-field-types/xy-shape.md

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


They're both technically correct because these sentences are fragments, so they're dependent on omitted text, which could be whatever we want it to be. I vote for "throw" in order to maintain consistency with the preceding sentence.

natebower · 2022-11-03T20:04:36Z

_opensearch/supported-field-types/xy.md

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


Suggested change

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

natebower · 2022-11-03T20:06:32Z

_opensearch/supported-field-types/xy.md

+
+The following table lists all Cartesian field types that OpenSearch supports.
+
+Field data type | Description


"Field Data Type"? I believe we capitalize other multi-word table headings.

natebower · 2022-11-03T20:07:34Z

_opensearch/supported-field-types/xy.md

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


Suggested change

Currently, OpenSearch supports indexing and searching 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).

Currently, OpenSearch supports indexing and searching 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).

natebower · 2022-11-03T20:08:26Z

_opensearch/supported-field-types/xy.md

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


"...indexing and searching of Cartesian field types"?

Signed-off-by: Fanit Kolchina <[email protected]>

Adds xy point and shape documentation

f730d3f

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws self-assigned this Oct 14, 2022

Moved the github link

2791105

Signed-off-by: Fanit Kolchina <[email protected]>

Naarcha-AWS added the Needs SME Waiting on input from subject matter expert label Oct 17, 2022

Adds documentation for cartesian shapes

c6ed43f

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws added 3 - Tech review PR: Tech review in progress v2.4.0 'Issues and PRs related to version v2.4.0' and removed Needs SME Waiting on input from subject matter expert labels Oct 27, 2022

kolchfa-aws marked this pull request as ready for review October 27, 2022 15:57

kolchfa-aws requested a review from a team as a code owner October 27, 2022 15:57

Updated BBOX coordinates

56acf45

Signed-off-by: Fanit Kolchina <[email protected]>

navneet1v reviewed Oct 27, 2022

View reviewed changes

VijayanB reviewed Oct 27, 2022

View reviewed changes

kolchfa-aws added 2 commits October 28, 2022 09:26

Fixed typo

69ae432

Signed-off-by: Fanit Kolchina <[email protected]>

Updated links and GeoJSON

e38233a

Signed-off-by: Fanit Kolchina <[email protected]>

naveentatikonda reviewed Oct 28, 2022

View reviewed changes

VijayanB approved these changes Nov 1, 2022

View reviewed changes

vagimeli approved these changes Nov 2, 2022

View reviewed changes

ariamarble reviewed Nov 2, 2022

View reviewed changes

ariamarble approved these changes Nov 2, 2022

View reviewed changes

kolchfa-aws added 2 commits November 2, 2022 20:24

Incorporated doc review comments

f340f08

Signed-off-by: Fanit Kolchina <[email protected]>

One more doc review comment

eac1d88

Signed-off-by: Fanit Kolchina <[email protected]>

natebower reviewed Nov 3, 2022

View reviewed changes

Incorporated editorial comments

e98f233

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws merged commit 9122bbb into main Nov 4, 2022

Naarcha-AWS deleted the xy-point branch December 13, 2022 19:55


		# 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/8_5_1/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/).


		# 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/8_3_0/sandbox/org/apache/lucene/document/XYShape.html) field type. To index a geoshape, OpenSearch tesselates the shape into a triangular mesh and stores each triangle in a BKD tree. This provides a 10<sup>-7</sup>decimal degree of precision, which represents near-perfect spatial resolution.


		- A [Well-Known Text](https://docs.opengeospatial.org/is/12-063r5/12-063r5.html) POINT in the "POINT(`x` `y`)" format

		```json


		## Spatial relations

		When you provide an xy shape to the xy query, the xy fields are matched using following spatial relations to the provided shape:


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


		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 tesselates the shape into a triangular mesh and stores each triangle in a BKD tree. 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/).


		A multiline string is an array of line strings.

		Index a line string in GeoJSON format:


		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, CAD, and amusement park and sporting venue mapping.


		Cartesian field types work well for spatial applications like virtual reality, 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/).

	[`null_value`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/index#null-value) \| A value to be used in place of `null`. 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`.
	[`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`.

	The examples below 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.
	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.

	Refer to the following image to visualize the example. Both the point and the polygon are within the bounding envelope:
	Refer to the following image to visualize the example. Both the point and the polygon are within the bounding envelope.


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


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


		The following table lists all Cartesian field types that OpenSearch supports.

		Field data type \| Description

	Currently, OpenSearch supports indexing and searching 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).
	Currently, OpenSearch supports indexing and searching 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).

Adds xy point and shape documentation #1564

Adds xy point and shape documentation #1564

Conversation

kolchfa-aws commented Oct 14, 2022

Checklist

kolchfa-aws commented Oct 27, 2022

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

VijayanB Oct 27, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

naveentatikonda Oct 28, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vagimeli 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

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

ariamarble 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

VijayanB Oct 27, 2022 •

edited

Loading

naveentatikonda Oct 28, 2022 •

edited

Loading