Added documentation on GeoJSON format for points and geo-points (#86066)

craigtaverner · web-flow · commit 68f432275d74 · 2022-04-28T10:41:07.000+02:00
* Added documentation on GeoJSON format for points

And geo-points.

* Fixed some small mistakes in painless geo-point
diff --git a/docs/painless/painless-contexts/painless-runtime-fields-context.asciidoc b/docs/painless/painless-contexts/painless-runtime-fields-context.asciidoc
@@ -15,7 +15,7 @@ about how to use runtime fields.
         Accepts the values from the script valuation. Scripts can call the
         `emit` method multiple times to emit multiple values.
 +
-The `emit` method applies only to scripts used in a 
+The `emit` method applies only to scripts used in a
 <<painless-execute-runtime-context,runtime fields context>>.
 +
 IMPORTANT: The `emit` method cannot accept `null` values. Do not call this
@@ -30,7 +30,7 @@ The signature for `emit` depends on the `type` of the field.
 `boolean`::   `emit(boolean)`
 `date`::      `emit(long)`
 `double`::    `emit(double)`
-`geo_point`:: `emit(double lat, double long)`
+`geo_point`:: `emit(double lat, double lon)`
 `ip`::        `emit(String)`
 `long`::      `emit(long)`
 `keyword`::   `emit(String)`
diff --git a/docs/painless/painless-guide/painless-execute-script.asciidoc b/docs/painless/painless-guide/painless-execute-script.asciidoc
@@ -77,8 +77,9 @@ sorted list of `double` values. See
 <<painless-runtime-double,double_field context>>.
 
 `geo_point_field`::
-The context for {ref}/geo-point.html[`geo-point` fields]. `emit` takes a
-`geo-point` value and the script returns coordinates for the geo point. See
+The context for {ref}/geo-point.html[`geo-point` fields]. `emit` takes two double
+parameters, the latitude and longitude values, and the script returns an object in
+GeoJSON format containing the coordinates for the geo point. See
 <<painless-runtime-geo,geo_point_field context>>.
 
 `ip_field`::
@@ -589,7 +590,7 @@ PUT /my-index-000001/
       "lat": {
         "type": "double"
       },
-     "lon": {
+      "lon": {
         "type": "double"
       }
     }
@@ -598,7 +599,7 @@ PUT /my-index-000001/
 ----
 
 You can then use the `geo_point_field` runtime field context to write a script
-that retrieves the `lat` and `long` values.
+that retrieves the `lat` and `lon` values.
 
 [source,console]
 ----
@@ -621,7 +622,7 @@ POST /_scripts/painless/_execute
 ----
 // TEST[continued]
 
-Because this you're working with a geo-point field type, the response includes
+Because you're working with a geo-point field type, the response includes
 results that are formatted as `coordinates`.
 
 [source,console-result]
@@ -639,6 +640,10 @@ results that are formatted as `coordinates`.
 }
 ----
 
+[NOTE]
+The emit function for {ref}/geo-point.html[geo-point] fields takes two parameters ordered with
+`lat` before `lon`, but the output GeoJSON format orders the `coordinates` as `[ lon, lat ]`.
+
 [[painless-runtime-ip]]
 ===== `ip_field`
 The `ip_field` context is useful for data that includes IP addresses of type
diff --git a/docs/reference/mapping/types/geo-point.asciidoc b/docs/reference/mapping/types/geo-point.asciidoc
@@ -14,7 +14,7 @@ Fields of type `geo_point` accept latitude-longitude pairs, which can be used:
 * to integrate distance into a document's <<query-dsl-function-score-query,relevance score>>.
 * to <<geo-sorting,sort>> documents by distance.
 
-There are five ways that a geopoint may be specified, as demonstrated below:
+There are six ways that a geopoint may be specified, as demonstrated below:
 
 [source,console]
 --------------------------------------------------
@@ -31,7 +31,7 @@ PUT my-index-000001
 
 PUT my-index-000001/_doc/1
 {
-  "text": "Geopoint as an object",
+  "text": "Geopoint as an object with 'lat' and 'lon' keys",
   "location": { <1>
     "lat": 41.12,
     "lon": -71.34
@@ -40,32 +40,41 @@ PUT my-index-000001/_doc/1
 
 PUT my-index-000001/_doc/2
 {
-  "text": "Geopoint as a string",
-  "location": "41.12,-71.34" <2>
+  "text": "Geopoint as an object using GeoJSON format",
+  "location": { <2>
+    "type": "Point",
+    "coordinates": [-71.34, 41.12]
+  }
 }
 
 PUT my-index-000001/_doc/3
 {
-  "text": "Geopoint as a geohash",
-  "location": "drm3btev3e86" <3>
+  "text": "Geopoint as a string",
+  "location": "41.12,-71.34" <3>
 }
 
 PUT my-index-000001/_doc/4
 {
-  "text": "Geopoint as an array",
-  "location": [ -71.34, 41.12 ] <4>
+  "text": "Geopoint as a geohash",
+  "location": "drm3btev3e86" <4>
 }
 
 PUT my-index-000001/_doc/5
+{
+  "text": "Geopoint as an array",
+  "location": [ -71.34, 41.12 ] <5>
+}
+
+PUT my-index-000001/_doc/6
 {
   "text": "Geopoint as a WKT POINT primitive",
-  "location" : "POINT (-71.34 41.12)" <5>
+  "location" : "POINT (-71.34 41.12)" <6>
 }
 
 GET my-index-000001/_search
 {
   "query": {
-    "geo_bounding_box": { <6>
+    "geo_bounding_box": { <7>
       "location": {
         "top_left": {
           "lat": 42,
@@ -82,22 +91,26 @@ GET my-index-000001/_search
 --------------------------------------------------
 
 <1> Geopoint expressed as an object, with `lat` and `lon` keys.
-<2> Geopoint expressed as a string with the format: `"lat,lon"`.
-<3> Geopoint expressed as a geohash.
-<4> Geopoint expressed as an array with the format: [ `lon`, `lat`]
-<5> Geopoint expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
+<2> Geopoint expressed as an object, in https://geojson.org/[GeoJSON] format, with `type` and `coordinates` keys.
+<3> Geopoint expressed as a string with the format: `"lat,lon"`.
+<4> Geopoint expressed as a geohash.
+<5> Geopoint expressed as an array with the format: [ `lon`, `lat`]
+<6> Geopoint expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
 POINT with the format: `"POINT(lon lat)"`
-<6> A geo-bounding box query which finds all geopoints that fall inside the box.
+<7> A geo-bounding box query which finds all geopoints that fall inside the box.
 
 [IMPORTANT]
 .Geopoints expressed as an array or string
 ==================================================
 
 Please note that string geopoints are ordered as `lat,lon`, while array
-geopoints are ordered as the reverse: `lon,lat`.
+geopoints, GeoJSON and WKT are ordered as the reverse: `lon,lat`.
 
-Originally, `lat,lon` was used for both array and string, but the array
-format was changed early on to conform to the format used by GeoJSON.
+The reasons for this are historical. Geographers traditionally write `latitude`
+before `longitude`, while recent formats specified for geographic data like
+https://geojson.org/[GeoJSON] and https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
+order `longitude` before `latitude` (easting before northing) in order to match
+the mathematical convention of ordering `x` before `y`.
 
 ==================================================
 
diff --git a/docs/reference/mapping/types/point.asciidoc b/docs/reference/mapping/types/point.asciidoc
@@ -12,7 +12,7 @@ coordinate system.
 You can query documents using this type using
 <<query-dsl-shape-query,shape Query>>.
 
-There are four ways that a point may be specified, as demonstrated below:
+There are five ways that a point may be specified, as demonstrated below:
 
 [source,console]
 --------------------------------------------------
@@ -29,40 +29,53 @@ PUT my-index-000001
 
 PUT my-index-000001/_doc/1
 {
-  "text": "Point as an object",
+  "text": "Point as an object with 'x' and 'y' keys",
   "location": { <1>
-    "x": 41.12,
-    "y": -71.34
+    "x": -71.34,
+    "y": 41.12
   }
 }
 
 PUT my-index-000001/_doc/2
 {
-  "text": "Point as a string",
-  "location": "41.12,-71.34" <2>
+  "text": "Point as an object using GeoJSON format",
+  "location": { <2>
+    "type": "Point",
+    "coordinates": [-71.34, 41.12]
+  }
 }
 
+PUT my-index-000001/_doc/3
+{
+  "text": "Point as a string",
+  "location": "-71.34,41.12" <3>
+}
 
 PUT my-index-000001/_doc/4
 {
   "text": "Point as an array",
-  "location": [41.12, -71.34] <3>
+  "location": [ -71.34, 41.12 ] <4>
 }
 
 PUT my-index-000001/_doc/5
 {
   "text": "Point as a WKT POINT primitive",
-  "location" : "POINT (41.12 -71.34)" <4>
+  "location" : "POINT (-71.34 41.12)" <5>
 }
 
 --------------------------------------------------
 
 <1> Point expressed as an object, with `x` and `y` keys.
-<2> Point expressed as a string with the format: `"x,y"`.
-<3> Point expressed as an array with the format: [ `x`, `y`]
-<4> Point expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
+<2> Point expressed as an object, in https://geojson.org/[GeoJSON] format, with `type` and `coordinates` keys.
+<3> Point expressed as a string with the format: `"x,y"`.
+<4> Point expressed as an array with the format: [ `x`, `y`]
+<5> Point expressed as a https://docs.opengeospatial.org/is/12-063r5/12-063r5.html[Well-Known Text]
 POINT with the format: `"POINT(x y)"`
 
+[NOTE]
+Unlike the case with the {ref}/geo-point.html[geo-point] field type,
+the order of the coordinates `x` and `y` is the same for all formats above.
+
 The coordinates provided to the indexer are single precision floating point values so
 the field guarantees the same accuracy provided by the java virtual machine (typically
 `1E-38`).
