diff --git a/docs/reference/mapping/types/geo-shape.asciidoc b/docs/reference/mapping/types/geo-shape.asciidoc index 2565ae5f320ff..0eee58a1a2f90 100644 --- a/docs/reference/mapping/types/geo-shape.asciidoc +++ b/docs/reference/mapping/types/geo-shape.asciidoc @@ -5,7 +5,7 @@ ++++ The `geo_shape` data type facilitates the indexing of and searching -with arbitrary geo shapes such as rectangles and polygons. It should be +with arbitrary geoshapes such as rectangles and polygons. It should be used when either the data being indexed or the queries being executed contain shapes other than just points. @@ -26,7 +26,7 @@ type. |`orientation` a|Optional. Default <> for the field's -polygons. +WKT polygons. This parameter sets and returns only a `RIGHT` (counterclockwise) or `LEFT` (clockwise) value. However, you can specify either value in multiple ways. @@ -66,7 +66,7 @@ and reject the whole document. [[geoshape-indexing-approach]] [discrete] ==== Indexing approach -GeoShape types are indexed by decomposing the shape into a triangular mesh and +Geoshape types are indexed by decomposing the shape into a triangular mesh and indexing each triangle as a 7 dimension point in a BKD tree. This provides near perfect spatial resolution (down to 1e-7 decimal degree precision) since all spatial relations are computed using an encoded vector representation of the @@ -144,7 +144,7 @@ API. The following is an example of a point in GeoJSON. POST /example/_doc { "location" : { - "type" : "point", + "type" : "Point", "coordinates" : [-77.03653, 38.897676] } } @@ -164,23 +164,23 @@ POST /example/_doc [[geo-linestring]] ===== http://geojson.org/geojson-spec.html#id3[LineString] -A `linestring` defined by an array of two or more positions. By -specifying only two points, the `linestring` will represent a straight +A linestring defined by an array of two or more positions. By +specifying only two points, the linestring will represent a straight line. Specifying more than two points creates an arbitrary path. The -following is an example of a LineString in GeoJSON. +following is an example of a linestring in GeoJSON. [source,console] -------------------------------------------------- POST /example/_doc { "location" : { - "type" : "linestring", + "type" : "LineString", "coordinates" : [[-77.03653, 38.897676], [-77.009051, 38.889939]] } } -------------------------------------------------- -The following is an example of a LineString in WKT: +The following is an example of a linestring in WKT: [source,console] -------------------------------------------------- @@ -190,7 +190,7 @@ POST /example/_doc } -------------------------------------------------- -The above `linestring` would draw a straight line starting at the White +The above linestring would draw a straight line starting at the White House to the US Capitol Building. [discrete] @@ -199,14 +199,14 @@ House to the US Capitol Building. A polygon is defined by a list of a list of points. The first and last points in each (outer) list must be the same (the polygon must be -closed). The following is an example of a Polygon in GeoJSON. +closed). The following is an example of a polygon in GeoJSON. [source,console] -------------------------------------------------- POST /example/_doc { "location" : { - "type" : "polygon", + "type" : "Polygon", "coordinates" : [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ] ] @@ -214,7 +214,7 @@ POST /example/_doc } -------------------------------------------------- -The following is an example of a Polygon in WKT: +The following is an example of a polygon in WKT: [source,console] -------------------------------------------------- @@ -233,7 +233,7 @@ of a polygon with a hole: POST /example/_doc { "location" : { - "type" : "polygon", + "type" : "Polygon", "coordinates" : [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ], [ [100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2] ] @@ -242,7 +242,7 @@ POST /example/_doc } -------------------------------------------------- -The following is an example of a Polygon with a hole in WKT: +The following is an example of a polygon with a hole in WKT: [source,console] -------------------------------------------------- @@ -257,22 +257,29 @@ POST /example/_doc ===== Polygon orientation A polygon's orientation indicates the order of its vertices: `RIGHT` -(counterclockwise) or `LEFT` (clockwise). +(counterclockwise) or `LEFT` (clockwise). {es} uses a polygon’s orientation to +determine if it crosses the international dateline (+/-180° longitude). -You can set a default orientation for a `geo_shape` field using the -<>. You can override -this default for specific polygons using the document-level `orientation` -parameter. +You can set a default orientation for WKT polygons using the +<>. This is because +the WKT specification doesn't specify or enforce a default orientation. -For example, the following indexing request specifies a document-level -`orientation` of `LEFT`. +GeoJSON polygons use a default orientation of `RIGHT`, regardless of +`orientation` mapping parameter's value. This is because the +https://tools.ietf.org/html/rfc7946#section-3.1.6[GeoJSON specification] +mandates that an outer polygon use a counterclockwise orientation and interior +shapes use a clockwise orientation. + +You can override the default orientation for GeoJSON polygons using the +document-level `orientation` parameter. For example, the following indexing +request specifies a document-level `orientation` of `LEFT`. [source,console] ---- POST /example/_doc { "location" : { - "type" : "polygon", + "type" : "Polygon", "orientation" : "LEFT", "coordinates" : [ [ [-177.0, 10.0], [176.0, 15.0], [172.0, 0.0], [176.0, -15.0], [-177.0, -10.0], [-177.0, 10.0] ] @@ -282,15 +289,15 @@ POST /example/_doc ---- {es} only uses a polygon’s orientation to determine if it crosses the -international dateline (+/-180° longitude). If the difference between a -polygon’s minimum longitude and the maximum longitude is less than 180°, the -polygon doesn't cross the dateline and its orientation has no effect. +international dateline. If the difference between a polygon’s minimum longitude +and the maximum longitude is less than 180°, the polygon doesn't cross the +dateline and its orientation has no effect. If the difference between a polygon’s minimum longitude and the maximum longitude is 180° or greater, {es} checks whether the polygon's document-level -`orientation` differs from the default in the `orientation` mapping parameter. -If the orientation differs, {es} considers the polygon to cross the -international dateline and splits the polygon at the dateline. +`orientation` differs from the default orientation. If the orientation differs, +{es} considers the polygon to cross the international dateline and splits the +polygon at the dateline. [discrete] [[geo-multipoint]] @@ -303,7 +310,7 @@ The following is an example of a list of GeoJSON points: POST /example/_doc { "location" : { - "type" : "multipoint", + "type" : "MultiPoint", "coordinates" : [ [102.0, 2.0], [103.0, 2.0] ] @@ -332,7 +339,7 @@ The following is an example of a list of GeoJSON linestrings: POST /example/_doc { "location" : { - "type" : "multilinestring", + "type" : "MultiLineString", "coordinates" : [ [ [102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0] ], [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0] ], @@ -363,7 +370,7 @@ The following is an example of a list of GeoJSON polygons (second polygon contai POST /example/_doc { "location" : { - "type" : "multipolygon", + "type" : "MultiPolygon", "coordinates" : [ [ [[102.0, 2.0], [103.0, 2.0], [103.0, 3.0], [102.0, 3.0], [102.0, 2.0]] ], [ [[100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]], @@ -394,14 +401,14 @@ The following is an example of a collection of GeoJSON geometry objects: POST /example/_doc { "location" : { - "type": "geometrycollection", + "type": "GeometryCollection", "geometries": [ { - "type": "point", + "type": "Point", "coordinates": [100.0, 0.0] }, { - "type": "linestring", + "type": "LineString", "coordinates": [ [101.0, 0.0], [102.0, 1.0] ] } ]