WARNING: Version 1.7 of Elasticsearch has passed its EOL date.
This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.
GeoShape Filter
editGeoShape Filter
editFilter documents indexed using the geo_shape
type.
Requires the geo_shape Mapping.
You may also use the geo_shape Query.
The geo_shape
Filter 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 PrefixTree configuration
as defined for the field mapping.
Filter Format
editThe Filter supports two ways of defining the Filter shape, either by providing a whole shape defintion, or by referencing the name of a shape pre-indexed in another index. Both formats are defined below with examples.
Provided Shape Definition
editSimilar to the geo_shape
type, the geo_shape
Filter uses
GeoJSON to represent shapes.
Given a document that looks like this:
{ "name": "Wind & Wetter, Berlin, Germany", "location": { "type": "Point", "coordinates": [13.400544, 52.530286] } }
The following query will find the point using the Elasticsearch’s
envelope
GeoJSON extension:
{ "query":{ "filtered": { "query": { "match_all": {} }, "filter": { "geo_shape": { "location": { "shape": { "type": "envelope", "coordinates" : [[13.0, 53.0], [14.0, 52.0]] } } } } } } }
Pre-Indexed Shape
editThe Filter also supports using a shape which has already been indexed in another index and/or index type. 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. -
type
- Index type where the pre-indexed shape is. -
path
- The field specified as path containing the pre-indexed shape. Defaults to shape.
The following is an example of using the Filter with a pre-indexed shape:
{ "filtered": { "query": { "match_all": {} }, "filter": { "geo_shape": { "location": { "indexed_shape": { "id": "DEU", "type": "countries", "index": "shapes", "path": "location" } } } } } }
Caching
editThe result of the Filter is not cached by default. Setting _cache
to
true
will mean the results of the Filter will be cached. Since shapes
can contain 10s-100s of coordinates and any one differing means a new
shape, it may make sense to only using caching when you are sure that
the shapes will remain reasonably static.