Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 2 commits into from
Apr 28, 2022
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
74d6ce7
Added documentation on GeoJSON format for points
craigtaverner Apr 21, 2022
f11d863
Fixed some small mistakes in painless geo-point
craigtaverner Apr 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/painless/painless-contexts/painless-runtime-fields-context.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)`
Expand Down
15 changes: 10 additions & 5 deletions docs/painless/painless-guide/painless-execute-script.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@iverase Could you verify this change. I think the old description seemed quite incorrect.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had a look and yes the explanation of the emit is correct, thanks! What it is not clear to me what we refer here to what the script returns. This is currently a bug as it should behave as an indexed geo_point which is not the case.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, this geo_point context is different to the out put of the fields API. lThe change looks good to me then.

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`::
Expand Down Expand Up @@ -589,7 +590,7 @@ PUT /my-index-000001/
"lat": {
"type": "double"
},
"lon": {
"lon": {
"type": "double"
}
}
Expand All @@ -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]
----
Expand All @@ -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]
Expand All @@ -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
Expand Down
49 changes: 31 additions & 18 deletions docs/reference/mapping/types/geo-point.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
--------------------------------------------------
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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`.
==================================================

Expand Down
35 changes: 24 additions & 11 deletions docs/reference/mapping/types/point.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
--------------------------------------------------
Expand All @@ -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`).
Expand Down