317 lines
7.3 KiB
Plaintext
317 lines
7.3 KiB
Plaintext
[[query-dsl-geo-shape-query]]
|
|
=== Geo-shape query
|
|
++++
|
|
<titleabbrev>Geo-shape</titleabbrev>
|
|
++++
|
|
|
|
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>>.
|
|
|
|
The `geo_shape` query uses the same grid square representation as the
|
|
`geo_shape` mapping to find documents that have a shape that intersects
|
|
with the query shape. It will also use the same Prefix Tree configuration
|
|
as defined for the field mapping.
|
|
|
|
The query supports two ways of defining the query shape, either by
|
|
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
|
|
http://geojson.org[GeoJSON] to represent shapes.
|
|
|
|
Given the following index with locations as `geo_shape` fields:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /example
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"location": {
|
|
"type": "geo_shape"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
POST /example/_doc?refresh
|
|
{
|
|
"name": "Wind & Wetter, Berlin, Germany",
|
|
"location": {
|
|
"type": "point",
|
|
"coordinates": [ 13.400544, 52.530286 ]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTSETUP
|
|
|
|
|
|
The following query will find the point using {es}'s `envelope` GeoJSON
|
|
extension:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /example/_search
|
|
{
|
|
"query": {
|
|
"bool": {
|
|
"must": {
|
|
"match_all": {}
|
|
},
|
|
"filter": {
|
|
"geo_shape": {
|
|
"location": {
|
|
"shape": {
|
|
"type": "envelope",
|
|
"coordinates": [ [ 13.0, 53.0 ], [ 14.0, 52.0 ] ]
|
|
},
|
|
"relation": "within"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
|
|
The above query can, similarly, be queried on `geo_point` fields.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /example_points
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"location": {
|
|
"type": "geo_point"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
PUT /example_points/_doc/1?refresh
|
|
{
|
|
"name": "Wind & Wetter, Berlin, Germany",
|
|
"location": [13.400544, 52.530286]
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
|
|
Using the same query, the documents with matching `geo_point` fields are
|
|
returned.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /example_points/_search
|
|
{
|
|
"query": {
|
|
"bool": {
|
|
"must": {
|
|
"match_all": {}
|
|
},
|
|
"filter": {
|
|
"geo_shape": {
|
|
"location": {
|
|
"shape": {
|
|
"type": "envelope",
|
|
"coordinates": [ [ 13.0, 53.0 ], [ 14.0, 52.0 ] ]
|
|
},
|
|
"relation": "intersects"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TEST[continued]
|
|
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"took" : 17,
|
|
"timed_out" : false,
|
|
"_shards" : {
|
|
"total" : 1,
|
|
"successful" : 1,
|
|
"skipped" : 0,
|
|
"failed" : 0
|
|
},
|
|
"hits" : {
|
|
"total" : {
|
|
"value" : 1,
|
|
"relation" : "eq"
|
|
},
|
|
"max_score" : 1.0,
|
|
"hits" : [
|
|
{
|
|
"_index" : "example_points",
|
|
"_type" : "_doc",
|
|
"_id" : "1",
|
|
"_score" : 1.0,
|
|
"_source" : {
|
|
"name": "Wind & Wetter, Berlin, Germany",
|
|
"location": [13.400544, 52.530286]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// 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 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.
|
|
Defaults to 'shape'.
|
|
* `routing` - The routing of the shape document if required.
|
|
|
|
The following is an example of using the Filter with a pre-indexed
|
|
shape:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /shapes
|
|
{
|
|
"mappings": {
|
|
"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": {
|
|
"filter": {
|
|
"geo_shape": {
|
|
"location": {
|
|
"indexed_shape": {
|
|
"index": "shapes",
|
|
"id": "deu",
|
|
"path": "location"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
|
|
==== Spatial Relations
|
|
|
|
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`:
|
|
|
|
* `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.
|
|
|
|
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.
|
|
|
|
|
|
[discrete]
|
|
==== Ignore Unmapped
|
|
|
|
When set to `true` the `ignore_unmapped` option will ignore an unmapped field
|
|
and will not match any documents for this query. This can be useful when
|
|
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:
|
|
|
|
* `POINT`
|
|
* `LINE`
|
|
* `MULTIPOINT`
|
|
* `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.
|
|
|
|
|
|
* 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"
|
|
}
|
|
}
|
|
--------------------------------------------------
|