From 536dadc4e040be534152cc1d0504a72b8083d0ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Istv=C3=A1n=20Zolt=C3=A1n=20Szab=C3=B3?= Date: Mon, 8 Jun 2020 15:03:59 +0200 Subject: [PATCH] [DOCS] Extends geo_shape query docs to explain behavior when data is indexed as array of shapes (#57806) Co-authored-by: James Rodewig --- .../query-dsl/geo-shape-query.asciidoc | 104 +++++++++++++----- 1 file changed, 77 insertions(+), 27 deletions(-) diff --git a/docs/reference/query-dsl/geo-shape-query.asciidoc b/docs/reference/query-dsl/geo-shape-query.asciidoc index 74b05cc2b9b..6ef87f71f0d 100644 --- a/docs/reference/query-dsl/geo-shape-query.asciidoc +++ b/docs/reference/query-dsl/geo-shape-query.asciidoc @@ -6,7 +6,8 @@ Filter documents indexed using the `geo_shape` or `geo_point` type. -Requires the <> or the <>. +Requires the <> or the +<>. The `geo_shape` query uses the same grid square representation as the `geo_shape` mapping to find documents that have a shape that intersects @@ -18,6 +19,7 @@ providing a whole shape definition, or by referencing the name of a shape pre-indexed in another index. Both formats are defined below with examples. + ==== Inline Shape Definition Similar to the `geo_shape` type, the `geo_shape` query uses @@ -49,8 +51,9 @@ POST /example/_doc?refresh -------------------------------------------------- // TESTSETUP -The following query will find the point using the Elasticsearch's -`envelope` GeoJSON extension: + +The following query will find the point using {es}'s `envelope` GeoJSON +extension: [source,console] -------------------------------------------------- @@ -77,6 +80,7 @@ GET /example/_search } -------------------------------------------------- + The above query can, similarly, be queried on `geo_point` fields. [source,console] @@ -100,7 +104,9 @@ PUT /example_points/_doc/1?refresh -------------------------------------------------- // TEST[continued] -Using the same query, the documents with matching `geo_point` fields are returned + +Using the same query, the documents with matching `geo_point` fields are +returned. [source,console] -------------------------------------------------- @@ -162,19 +168,19 @@ GET /example_points/_search -------------------------------------------------- // TESTRESPONSE[s/"took" : 17/"took" : $body.took/] + ==== Pre-Indexed Shape -The Query also supports using a shape which has already been indexed in -another index. This is particularly useful for when -you have a pre-defined list of shapes which are useful to your -application and you want to reference this using a logical name (for -example 'New Zealand') rather than having to provide their coordinates -each time. In this situation it is only necessary to provide: +The query also supports using a shape which has already been indexed in another +index. This is particularly useful for when you have a pre-defined list of +shapes and you want to reference the list using +a logical name (for example 'New Zealand') rather than having to provide +coordinates each time. In this situation, it is only necessary to provide: * `id` - The ID of the document that containing the pre-indexed shape. -* `index` - Name of the index where the pre-indexed shape is. Defaults -to 'shapes'. -* `path` - The field specified as path containing the pre-indexed shape. +* `index` - Name of the index where the pre-indexed shape is. Defaults to +'shapes'. +* `path` - The field specified as path containing the pre-indexed shape. Defaults to 'shape'. * `routing` - The routing of the shape document if required. @@ -222,27 +228,31 @@ GET /example/_search } -------------------------------------------------- + ==== Spatial Relations -The <> mapping parameter determines -which spatial relation operators may be used at search time. +The <> mapping parameter determines which +spatial relation operators may be used at search time. -The following is a complete list of spatial relation operators available when searching a field of type `geo_shape`: +The following is a complete list of spatial relation operators available when +searching a field of type `geo_shape`: * `INTERSECTS` - (default) Return all documents whose `geo_shape` field intersects the query geometry. -* `DISJOINT` - Return all documents whose `geo_shape` field -has nothing in common with the query geometry. -* `WITHIN` - Return all documents whose `geo_shape` field -is within the query geometry. -* `CONTAINS` - Return all documents whose `geo_shape` field -contains the query geometry. +* `DISJOINT` - Return all documents whose `geo_shape` field has nothing in +common with the query geometry. +* `WITHIN` - Return all documents whose `geo_shape` field is within the query +geometry. +* `CONTAINS` - Return all documents whose `geo_shape` field contains the query +geometry. -When searching a field of type `geo_point` there is a single supported spatial relation operator: +When searching a field of type `geo_point` there is a single supported spatial +relation operator: -* `INTERSECTS` - (default) Return all documents whose `geo_point` field +* `INTERSECTS` - (default) Return all documents whose `geo_point` field intersects the query geometry. + [float] ==== Ignore Unmapped @@ -252,9 +262,11 @@ querying multiple indexes which might have different mappings. When set to `false` (the default value) the query will throw an exception if the field is not mapped. + ==== Shape Types supported for Geo-Point -When searching a field of type `geo_point` the following shape types are not supported: +When searching a field of type `geo_point` the following shape types are not +supported: * `POINT` * `LINE` @@ -262,5 +274,43 @@ When searching a field of type `geo_point` the following shape types are not sup * `MULTILINE` ==== Notes -Geo-shape queries on geo-shapes implemented with <> will not be executed if -<> is set to false. + +* Geo-shape queries on geo-shapes implemented with + <> will not be executed if + <> is set + to false. + + +* When data is indexed in a `geo_shape` field as an array of shapes, the arrays + are treated as one shape. For this reason, the following requests are + equivalent. + +[source,console] +-------------------------------------------------- +PUT /test/_doc/1 +{ + "location": [ + { + "coordinates": [46.25,20.14], + "type": "point" + }, + { + "coordinates": [47.49,19.04], + "type": "point" + } + ] +} +-------------------------------------------------- + + +[source,console] +-------------------------------------------------- +PUT /test/_doc/1 +{ + "location": + { + "coordinates": [[46.25,20.14],[47.49,19.04]], + "type": "multipoint" + } +} +--------------------------------------------------