[DOCS] Extends geo_shape query docs to explain behavior when data is indexed as array of shapes (#57806)
Co-authored-by: James Rodewig <james.rodewig@elastic.co>
This commit is contained in:
István Zoltán Szabó
parent
663702e609
commit
536dadc4e0
|
|
@ -6,7 +6,8 @@
|
|||
|
||||
Filter documents indexed using the `geo_shape` or `geo_point` type.
|
||||
|
||||
Requires the <<geo-shape,`geo_shape` Mapping>> or the <<geo-point,`geo_point` Mapping>>.
|
||||
Requires the <<geo-shape,`geo_shape` Mapping>> or the
|
||||
<<geo-point,`geo_point` 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
|
||||
|
|
@ -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,18 +168,18 @@ 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'.
|
||||
* `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 <<spatial-strategy, geo_shape strategy>> mapping parameter determines
|
||||
which spatial relation operators may be used at search time.
|
||||
The <<spatial-strategy, geo_shape strategy>> 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 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 <<prefix-trees, `PrefixTrees`>> will not be executed if
|
||||
<<query-dsl-allow-expensive-queries, `search.allow_expensive_queries`>> is set to false.
|
||||
|
||||
* Geo-shape queries on geo-shapes implemented with
|
||||
<<prefix-trees, `PrefixTrees`>> will not be executed if
|
||||
<<query-dsl-allow-expensive-queries, `search.allow_expensive_queries`>> 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"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
|
|
|
|||
Loading…
Reference in New Issue