191 lines
4.5 KiB
Plaintext
191 lines
4.5 KiB
Plaintext
[[query-dsl-shape-query]]
|
|
[role="xpack"]
|
|
[testenv="basic"]
|
|
=== Shape query
|
|
++++
|
|
<titleabbrev>Shape</titleabbrev>
|
|
++++
|
|
|
|
Queries documents that contain fields indexed using the `shape` type.
|
|
|
|
Requires the <<shape,`shape` Mapping>>.
|
|
|
|
The query supports two ways of defining the target shape, either by
|
|
providing a whole shape definition, or by referencing the name, or id, of a shape
|
|
pre-indexed in another index. Both formats are defined below with
|
|
examples.
|
|
|
|
==== Inline Shape Definition
|
|
|
|
Similar to the `geo_shape` query, the `shape` query uses
|
|
http://www.geojson.org[GeoJSON] or
|
|
https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[Well Known Text]
|
|
(WKT) to represent shapes.
|
|
|
|
Given the following index:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
PUT /example
|
|
{
|
|
"mappings": {
|
|
"properties": {
|
|
"geometry": {
|
|
"type": "shape"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
PUT /example/_doc/1?refresh=wait_for
|
|
{
|
|
"name": "Lucky Landing",
|
|
"geometry": {
|
|
"type": "point",
|
|
"coordinates": [ 1355.400544, 5255.530286 ]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTSETUP
|
|
|
|
The following query will find the point using the Elasticsearch's
|
|
`envelope` GeoJSON extension:
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
GET /example/_search
|
|
{
|
|
"query": {
|
|
"shape": {
|
|
"geometry": {
|
|
"shape": {
|
|
"type": "envelope",
|
|
"coordinates": [ [ 1355.0, 5355.0 ], [ 1400.0, 5200.0 ] ]
|
|
},
|
|
"relation": "within"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
////
|
|
[source,console-result]
|
|
--------------------------------------------------
|
|
{
|
|
"took": 3,
|
|
"timed_out": false,
|
|
"_shards": {
|
|
"total": 1,
|
|
"successful": 1,
|
|
"skipped": 0,
|
|
"failed": 0
|
|
},
|
|
"hits": {
|
|
"total": {
|
|
"value": 1,
|
|
"relation": "eq"
|
|
},
|
|
"max_score": 0.0,
|
|
"hits": [
|
|
{
|
|
"_index": "example",
|
|
"_type": "_doc",
|
|
"_id": "1",
|
|
"_score": 0.0,
|
|
"_source": {
|
|
"name": "Lucky Landing",
|
|
"geometry": {
|
|
"type": "point",
|
|
"coordinates": [
|
|
1355.400544,
|
|
5255.530286
|
|
]
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// TESTRESPONSE[s/"took": 3/"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:
|
|
|
|
* `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": {
|
|
"geometry": {
|
|
"type": "shape"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
PUT /shapes/_doc/footprint
|
|
{
|
|
"geometry": {
|
|
"type": "envelope",
|
|
"coordinates": [ [ 1355.0, 5355.0 ], [ 1400.0, 5200.0 ] ]
|
|
}
|
|
}
|
|
|
|
GET /example/_search
|
|
{
|
|
"query": {
|
|
"shape": {
|
|
"geometry": {
|
|
"indexed_shape": {
|
|
"index": "shapes",
|
|
"id": "footprint",
|
|
"path": "geometry"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
|
|
==== Spatial Relations
|
|
|
|
The following is a complete list of spatial relation operators available:
|
|
|
|
* `INTERSECTS` - (default) Return all documents whose `shape` field
|
|
intersects the query geometry.
|
|
* `DISJOINT` - Return all documents whose `shape` field
|
|
has nothing in common with the query geometry.
|
|
* `WITHIN` - Return all documents whose `shape` field
|
|
is within the query geometry.
|
|
* `CONTAINS` - Return all documents whose `shape` field
|
|
contains the query geometry.
|
|
|
|
[float]
|
|
==== 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.
|