GeoShape Filter

Filter 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.

The 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.

Similar 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]]
                        }
                    }
                }
            }
        }
    }
}

The 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:

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",
                        "shape_field_name": "location"
                    }
                }
            }
        }
    }
}

The 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.

Elasticsearch 0.90 changed the geo_shape implementation in a way that is not compatible. Prior to this version, there was a required relation field on queries and filter queries that indicated the relation of the query shape to the indexed shapes. Support for this was implemented in Elasticsearch and was poorly aligned with the underlying Lucene implementation, which has no notion of a relation. From 0.90, this field defaults to its only supported value: intersects. The other values of contains, within, disjoint are no longer supported. By using e.g. a bool filter, one can easily emulate disjoint. Given the imprecise accuracy (see geo_shape Mapping), within and contains were always somewhat problematic and intersects is generally good enough.