mirror of
https://github.com/honeymoose/OpenSearch.git
synced 2025-02-11 23:45:15 +00:00
5a2c6f0d4f
Plugin discovery documentation contained information about installing Elasticsearch 2.0 and installing an oracle JDK, both of which is no longer valid. While noticing that the instructions used cleartext HTTP to install packages, this commit replaces HTTPs links instead of HTTP where possible. In addition a few community links have been removed, as they do not seem to exist anymore. Co-authored-by: Alexander Reelsen <alexander@reelsen.net>
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"
|
|
}
|
|
}
|
|
--------------------------------------------------
|