diff --git a/docs/painless/painless-contexts/painless-runtime-fields-context.asciidoc b/docs/painless/painless-contexts/painless-runtime-fields-context.asciidoc index 0461b47fb47a6..592e0b9c2ca6a 100644 --- 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 <>. + 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 index 2b28f1574c1b3..d5da3bf29c97a 100644 --- 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 <>. `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 <>. `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 index d6e23c2bcef70..a05e7bc9d1cf0 100644 --- 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 <>. * to <> 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 index 17113f76753f6..b01ec7d11be02 100644 --- 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 <>. -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`).