Add geodistance query documentation (opensearch-project#7607)

* Add geodistance query documentation

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

* Add optional sentence

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

* Fix links

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

* More links

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

* Fix a link

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

* Apply suggestions from code review

Co-authored-by: Nathan Bower <nbower@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Editorial comment

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

---------

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Co-authored-by: Nathan Bower <nbower@amazon.com>

Author: kolchfa-aws

_api-reference/common-parameters.md

@@ -90,3 +90,37 @@ The following request specifies filters to limit the fields returned in the resp
 
 GET _search?filter_path=<field_name>.*,-<field_name>
 ```
+
+## Units
+
+OpenSearch APIs support the following units.
+
+### Time units
+
+The following table lists all supported time units.
+
+Units | Specify as
+:--- | :---
+Days | `d`
+Hours | `h`
+Minutes | `m`
+Seconds | `s`
+Milliseconds | `ms`
+Microseconds | `micros`
+Nanoseconds | `nanos`
+ 
+### Distance units
+
+The following table lists all supported distance units.
+
+Units | Specify as
+:--- | :---
+Miles | `mi` or `miles`
+Yards | `yd` or `yards`
+Feet | `ft` or `feet`
+Inches | `in` or `inch`
+Kilometers | `km` or `kilometers`
+Meters | `m` or `meters`
+Centimeters | `cm` or `centimeters`
+Millimeters | `mm` or `millimeters`
+Nautical miles | `NM`, `nmi`, or `nauticalmiles` 

_query-dsl/geo-and-xy/geo-bounding-box.md

@@ -31,6 +31,7 @@ PUT testindex1
   }
 }
 ```
+{% include copy-curl.html %}
 
 Index three geopoints as objects with latitudes and longitudes:
 
@@ -42,15 +43,21 @@ PUT testindex1/_doc/1
     "lon": 40.71
   }
 }
+```
+{% include copy-curl.html %}
 
+```json
 PUT testindex1/_doc/2
 {
   "point": { 
     "lat": 72.64,
     "lon": 22.62
   } 
 }
+```
+{% include copy-curl.html %}
 
+```json
 PUT testindex1/_doc/3
 {
   "point": { 
@@ -59,6 +66,7 @@ PUT testindex1/_doc/3
   }
 }
 ```
+{% include copy-curl.html %}
 
 Search for all documents and filter the documents whose points lie within the rectangle defined in the query:
 
@@ -88,6 +96,7 @@ GET testindex1/_search
   }
 }
 ```
+{% include copy-curl.html %}
 
 The response contains the matching document:
 
@@ -163,6 +172,7 @@ GET testindex1/_search
   }
 }
 ```
+{% include copy-curl.html %}
 
 ## Request fields
 
@@ -205,6 +215,7 @@ GET testindex1/_search
   }
 }
 ```
+{% include copy-curl.html %}
 
 To specify a bounding box that covers the whole area of a geohash, provide that geohash as both `top_left` and `bottom_right` parameters of the bounding box:
 
@@ -227,4 +238,5 @@ GET testindex1/_search
     }
   }
 }
-```
+```
+{% include copy-curl.html %}

_query-dsl/geo-and-xy/geodistance.md

@@ -0,0 +1,121 @@
+---
+layout: default
+title: Geodistance
+parent: Geographic and xy queries
+grand_parent: Query DSL
+nav_order: 20
+---
+
+# Geodistance query
+
+A geodistance query returns documents with geopoints that are within a specified distance from the provided geopoint. A document with multiple geopoints matches the query if at least one geopoint matches the query.
+
+The searched document field must be mapped as `geo_point`.
+{: .note}
+
+## Example
+
+Create a mapping with the `point` field mapped as `geo_point`:
+
+```json
+PUT testindex1
+{
+  "mappings": {
+    "properties": {
+      "point": {
+        "type": "geo_point"
+      }
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+Index a geopoint, specifying its latitude and longitude:
+
+```json
+PUT testindex1/_doc/1
+{
+  "point": { 
+    "lat": 74.00,
+    "lon": 40.71
+  }
+}
+```
+{% include copy-curl.html %}
+
+Search for documents whose `point` objects are within the specified `distance` from the specified `point`:
+
+```json
+GET /testindex1/_search
+{
+  "query": {
+    "bool": {
+      "must": {
+        "match_all": {}
+      },
+      "filter": {
+        "geo_distance": {
+          "distance": "50mi",
+          "point": {
+            "lat": 73.5,
+            "lon": 40.5
+          }
+        }
+      }
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+The response contains the matching document:
+
+```json
+{
+  "took": 5,
+  "timed_out": false,
+  "_shards": {
+    "total": 1,
+    "successful": 1,
+    "skipped": 0,
+    "failed": 0
+  },
+  "hits": {
+    "total": {
+      "value": 1,
+      "relation": "eq"
+    },
+    "max_score": 1,
+    "hits": [
+      {
+        "_index": "testindex1",
+        "_id": "1",
+        "_score": 1,
+        "_source": {
+          "point": {
+            "lat": 74,
+            "lon": 40.71
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+## Request fields
+
+Geodistance queries accept the following fields.
+
+Field | Data type | Description
+:--- | :--- | :--- 
+`_name` | String | The name of the filter. Optional.
+`distance` | String | The distance within which to match the points. This distance is the radius of a circle centered at the specified point. For supported distance units, see [Distance units]({{site.url}}{{site.baseurl}}/api-reference/common-parameters/#distance-units). Required.
+`distance_type` | String | Specifies how to calculate the distance. Valid values are `arc` or `plane` (faster but inaccurate for long distances or points close to the poles). Optional. Default is `arc`.
+`validation_method` | String | The validation method. Valid values are `IGNORE_MALFORMED` (accept geopoints with invalid coordinates), `COERCE` (try to coerce coordinates to valid values), and `STRICT` (return an error when coordinates are invalid). Optional. Default is `STRICT`.
+`ignore_unmapped` | Boolean | Specifies whether to ignore an unmapped field. If set to `true`, then the query does not return any documents that contain an unmapped field. If set to `false`, then an exception is thrown when the field is unmapped. Optional. Default is `false`.
+
+## Accepted formats
+
+You can specify the geopoint coordinates when indexing a document and searching for documents in any [format]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point#formats) accepted by the geopoint field type.  

_query-dsl/geo-and-xy/index.md

@@ -12,7 +12,7 @@ redirect_from:
 
 # Geographic and xy queries
 
-Geographic and xy queries let you search fields that contain points and shapes on a map or coordinate plane. Geographic queries work on geospatial data, while xy queries work on two-dimensional coordinate data. Out of all geographic queries, the geoshape query is very similar to the xy query, but the former searches [geographic fields]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geographic), while the latter searches [Cartesian fields]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy).
+Geographic and xy queries let you search fields that contain points and shapes on a map or coordinate plane. Geographic queries work on geospatial data, while xy queries work on two-dimensional coordinate data. Out of all geographic queries, the geoshape query is very similar to the xy query, but the former searches [geographic fields]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geographic/), while the latter searches [Cartesian fields]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy).
 
 ## xy queries
 
@@ -24,13 +24,13 @@ xy queries return documents that contain:
 
 ## Geographic queries
 
-Geographic queries search for documents that contain geospatial geometries. These geometries can be specified in [`geo_point`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point) fields, which support points on a map, and [`geo_shape`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-shape) fields, which support points, lines, circles, and polygons. 
+Geographic queries search for documents that contain geospatial geometries. These geometries can be specified in [`geo_point`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-point/) fields, which support points on a map, and [`geo_shape`]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/geo-shape/) fields, which support points, lines, circles, and polygons. 
 
 OpenSearch provides the following geographic query types:
 
 - [**Geo-bounding box queries**]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/geo-and-xy/geo-bounding-box/): Return documents with geopoint field values that are within a bounding box. 
-- **Geodistance queries** return documents with geopoints that are within a specified distance from the provided geopoint.
-- **Geopolygon queries** return documents with geopoints that are within a polygon.
-- **Geoshape queries** return documents that contain:
-    - geoshapes and geopoints that have one of four spatial relations to the provided shape: `INTERSECTS`, `DISJOINT`, `WITHIN`, or `CONTAINS`.
-    - geopoints that intersect the provided shape.
+- [**Geodistance queries**]({{site.url}}{{site.baseurl}}/query-dsl/geo-and-xy/geodistance/): Return documents with geopoints that are within a specified distance from the provided geopoint.
+- **Geopolygon queries**: Return documents with geopoints that are within a polygon.
+- **Geoshape queries**: Return documents that contain:
+    - Geoshapes and geopoints that have one of four spatial relations to the provided shape: `INTERSECTS`, `DISJOINT`, `WITHIN`, or `CONTAINS`.
+    - Geopoints that intersect the provided shape.

_query-dsl/geo-and-xy/xy.md

@@ -12,13 +12,13 @@ redirect_from:
 
 # xy query
 
-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. 
+To search for documents that contain [xy point]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/xy-point/) or [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
+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`
@@ -51,6 +51,7 @@ PUT testindex
   }
 }
 ```
+{% include copy-curl.html %}
 
 Index a document with a point and a document with a polygon:
 
@@ -62,7 +63,10 @@ PUT testindex/_doc/1
     "coordinates": [0.5, 3.0]
   }
 }
+```
+{% include copy-curl.html %}
 
+```json
 PUT testindex/_doc/2
 {
   "geometry" : {
@@ -77,6 +81,7 @@ PUT testindex/_doc/2
   }
 }
 ```
+{% include copy-curl.html %}
 
 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:
 
@@ -96,6 +101,7 @@ GET testindex/_search
   }
 }
 ```
+{% include copy-curl.html %}
 
 The following image depicts the example. Both the point and the polygon are within the bounding envelope.
 
@@ -200,6 +206,7 @@ PUT pre-indexed-shapes
   }
 }
 ```
+{% include copy-curl.html %}
 
 Index an envelope that specifies the boundaries and name it `rectangle`:
 
@@ -212,6 +219,7 @@ PUT pre-indexed-shapes/_doc/rectangle
   }
 }
 ```
+{% include copy-curl.html %}
 
 Index a document with a point and a document with a polygon into the index `testindex`:
 
@@ -223,7 +231,10 @@ PUT testindex/_doc/1
     "coordinates": [0.5, 3.0]
   }
 }
+```
+{% include copy-curl.html %}
 
+```json
 PUT testindex/_doc/2
 {
   "geometry" : {
@@ -238,6 +249,7 @@ PUT testindex/_doc/2
   }
 }
 ```
+{% include copy-curl.html %}
 
 Search for documents with shapes that intersect `rectangle` in the index `testindex` using a filter:
 
@@ -261,6 +273,7 @@ GET testindex/_search
   }
 }
 ```
+{% include copy-curl.html %}
 
 The preceding query uses the default spatial relation `INTERSECTS` and returns both the point and the polygon:
 
@@ -352,6 +365,7 @@ PUT testindex1
   }
 }
 ```
+{% include copy-curl.html %}
 
 Index three points:
 
@@ -360,17 +374,24 @@ PUT testindex1/_doc/1
 {
   "point": "1.0, 1.0" 
 }
+```
+{% include copy-curl.html %}
 
+```json
 PUT testindex1/_doc/2
 {
   "point": "2.0, 0.0" 
 }
+```
+{% include copy-curl.html %}
 
+```json
 PUT testindex1/_doc/3
 {
   "point": "-2.0, 2.0" 
 }
 ```
+{% include copy-curl.html %}
 
 Search for points that lie within the circle with the center at (0, 0) and a radius of 2:
 
@@ -390,6 +411,7 @@ GET testindex1/_search
   }
 }
 ```
+{% include copy-curl.html %}
 
 xy point only supports the default `INTERSECTS` spatial relation, so you don't need to provide the `relation` parameter.
 {: .note}