Skip to content

Commit

Permalink
CONSOLEify geo-shape docs
Browse files Browse the repository at this point in the history 
`CONSOLE`ify geo-shape type and geo-shape query docs.

Relates to #18160
  • Loading branch information
@nik9000
nik9000 committed Mar 31, 2017
1 parent e400ddd commit 439a092
Show file tree
Hide file tree
Showing 3 changed files with 98 additions and 30 deletions.
2 changes: 0 additions & 2 deletions docs/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,6 @@ buildRestTests.expectedUnconvertedCandidates = [
'reference/mapping/fields/all-field.asciidoc',
'reference/mapping/params/analyzer.asciidoc',
'reference/mapping/types/binary.asciidoc',
'reference/mapping/types/geo-shape.asciidoc',
'reference/mapping/types/ip.asciidoc',
'reference/mapping/types/nested.asciidoc',
'reference/mapping/types/object.asciidoc',
Expand All @@ -113,7 +112,6 @@ buildRestTests.expectedUnconvertedCandidates = [
'reference/modules/cross-cluster-search.asciidoc', // this is hart to test since we need 2 clusters -- maybe we can trick it into referencing itself...
'reference/query-dsl/exists-query.asciidoc',
'reference/query-dsl/function-score-query.asciidoc',
'reference/query-dsl/geo-shape-query.asciidoc',
'reference/search/field-stats.asciidoc',
'reference/search/profile.asciidoc',
'reference/search/request/highlighting.asciidoc',
Expand Down
50 changes: 43 additions & 7 deletions docs/reference/mapping/types/geo-shape.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -156,16 +156,23 @@ cell right next to it -- even though the shape is very close to the point.

[source,js]
--------------------------------------------------
PUT /example
{
"properties": {
"location": {
"type": "geo_shape",
"tree": "quadtree",
"precision": "1m"
"mappings": {
"doc": {
"properties": {
"location": {
"type": "geo_shape",
"tree": "quadtree",
"precision": "1m"
}
}
}
}
}
--------------------------------------------------
// CONSOLE
// TESTSETUP

This mapping maps the location field to the geo_shape type using the
quad_tree implementation and a precision of 1m. Elasticsearch translates
Expand Down Expand Up @@ -240,13 +247,15 @@ API.

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "point",
"coordinates" : [-77.03653, 38.897676]
}
}
--------------------------------------------------
// CONSOLE

[float]
===== http://geojson.org/geojson-spec.html#id3[LineString]
Expand All @@ -257,13 +266,15 @@ line. Specifying more than two points creates an arbitrary path.

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "linestring",
"coordinates" : [[-77.03653, 38.897676], [-77.009051, 38.889939]]
}
}
--------------------------------------------------
// CONSOLE

The above `linestring` would draw a straight line starting at the White
House to the US Capitol Building.
Expand All @@ -277,6 +288,7 @@ closed).

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "polygon",
Expand All @@ -286,12 +298,14 @@ closed).
}
}
--------------------------------------------------
// CONSOLE

The first array represents the outer boundary of the polygon, the other
arrays represent the interior shapes ("holes"):

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "polygon",
Expand All @@ -302,6 +316,8 @@ arrays represent the interior shapes ("holes"):
}
}
--------------------------------------------------
// CONSOLE
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]

*IMPORTANT NOTE:* GeoJSON does not mandate a specific order for vertices thus ambiguous
polygons around the dateline and poles are possible. To alleviate ambiguity
Expand All @@ -322,6 +338,7 @@ OGC standards to eliminate ambiguity resulting in a polygon that crosses the dat

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "polygon",
Expand All @@ -332,13 +349,16 @@ OGC standards to eliminate ambiguity resulting in a polygon that crosses the dat
}
}
--------------------------------------------------
// CONSOLE
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]

An `orientation` parameter can be defined when setting the geo_shape mapping (see <<geo-shape-mapping-options>>). This will define vertex
order for the coordinate list on the mapped geo_shape field. It can also be overridden on each document. The following is an example for
overriding the orientation on a document:

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "polygon",
Expand All @@ -350,6 +370,8 @@ overriding the orientation on a document:
}
}
--------------------------------------------------
// CONSOLE
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]

[float]
===== http://www.geojson.org/geojson-spec.html#id5[MultiPoint]
Expand All @@ -358,6 +380,7 @@ A list of geojson points.

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "multipoint",
Expand All @@ -367,6 +390,7 @@ A list of geojson points.
}
}
--------------------------------------------------
// CONSOLE

[float]
===== http://www.geojson.org/geojson-spec.html#id6[MultiLineString]
Expand All @@ -375,6 +399,7 @@ A list of geojson linestrings.

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "multilinestring",
Expand All @@ -386,6 +411,8 @@ A list of geojson linestrings.
}
}
--------------------------------------------------
// CONSOLE
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]

[float]
===== http://www.geojson.org/geojson-spec.html#id7[MultiPolygon]
Expand All @@ -394,18 +421,20 @@ A list of geojson polygons.

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"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]],
[[100.2, 0.2], [100.8, 0.2], [100.8, 0.8], [100.2, 0.8], [100.2, 0.2]] ]
]
}
}
--------------------------------------------------
// CONSOLE
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]

[float]
===== http://geojson.org/geojson-spec.html#geometrycollection[Geometry Collection]
Expand All @@ -414,6 +443,7 @@ A collection of geojson geometry objects.

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type": "geometrycollection",
Expand All @@ -430,7 +460,8 @@ A collection of geojson geometry objects.
}
}
--------------------------------------------------

// CONSOLE
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]

[float]
===== Envelope
Expand All @@ -441,13 +472,16 @@ bounding rectangle:

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "envelope",
"coordinates" : [ [-45.0, 45.0], [45.0, -45.0] ]
}
}
--------------------------------------------------
// CONSOLE
// TEST[skip:https://github.com/elastic/elasticsearch/issues/23836]

[float]
===== Circle
Expand All @@ -457,6 +491,7 @@ point with a radius:

[source,js]
--------------------------------------------------
POST /example/doc
{
"location" : {
"type" : "circle",
Expand All @@ -465,6 +500,7 @@ point with a radius:
}
}
--------------------------------------------------
// CONSOLE

Note: The inner `radius` field is required. If not specified, then
the units of the `radius` will default to `METERS`.
Expand Down
76 changes: 55 additions & 21 deletions docs/reference/query-dsl/geo-shape-query.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ Filter documents indexed using the `geo_shape` type.
Requires the <<geo-shape,`geo_shape` Mapping>>.

The `geo_shape` query uses the same grid square representation as the
geo_shape mapping to find documents that have a shape that intersects
`geo_shape` mapping to find documents that have a shape that intersects
with the query shape. It will also use the same PrefixTree configuration
as defined for the field mapping.

Expand All @@ -17,28 +17,44 @@ examples.

==== Inline Shape Definition

Similar to the `geo_shape` type, the `geo_shape` Filter uses
Similar to the `geo_shape` type, the `geo_shape` query uses
http://www.geojson.org[GeoJSON] to represent shapes.

Given a document that looks like this:
Given the following index:

[source,js]
--------------------------------------------------
PUT /example
{
"name": "Wind & Wetter, Berlin, Germany",
"location": {
"type": "Point",
"coordinates": [13.400544, 52.530286]
"mappings": {
"doc": {
"properties": {
"location": {
"type": "geo_shape"
}
}
}
}
}
POST /example/doc?refresh
{
"name": "Wind & Wetter, Berlin, Germany",
"location": {
"type": "point",
"coordinates": [13.400544, 52.530286]
}
}
--------------------------------------------------
// CONSOLE
// TESTSETUP

The following query will find the point using the Elasticsearch's
`envelope` GeoJSON extension:

[source,js]
--------------------------------------------------
GET /_search
GET /example/_search
{
"query":{
"bool": {
Expand Down Expand Up @@ -83,25 +99,43 @@ shape:

[source,js]
--------------------------------------------------
GET /_search
PUT /shapes
{
"mappings": {
"doc": {
"properties": {
"location": {
"type": "geo_shape"
}
}
}
}
}
PUT /shapes/doc/deu
{
"location": {
"type": "envelope",
"coordinates" : [[13.0, 53.0], [14.0, 52.0]]
}
}
GET /example/_search
{
"query": {
"bool": {
"must": {
"match_all": {}
},
"filter": {
"geo_shape": {
"location": {
"indexed_shape": {
"id": "DEU",
"type": "countries",
"index": "shapes",
"path": "location"
}
"filter": {
"geo_shape": {
"location": {
"indexed_shape": {
"index": "shapes",
"type": "doc",
"id": "deu",
"path": "location"
}
}
}
}
}
}
}
Expand Down

0 comments on commit 439a092

Please sign in to comment.