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.

Filter Format

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.

Provided Shape Definition

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]]
                        }
                    }
                }
            }
        }
    }
}
Pre-Indexed Shape

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:

  • 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

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.