[[query-dsl-geo-shape-query]]
== GeoShape Filter

Filter documents indexed using the `geo_shape` type.

Requires the <<mapping-geo-shape-type,geo_shape
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 PrefixTree configuration
as defined for the field mapping.

[float]
==== Filter Format

The Filter supports two ways of defining the Filter 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.

[float]
===== Provided Shape Definition

Similar to the `geo_shape` type, the `geo_shape` Filter uses
http://www.geojson.org[GeoJSON] to represent shapes.

Given a document that looks like this:

[source,js]
--------------------------------------------------
{
    "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:

[source,js]
--------------------------------------------------
{
    "query":{
        "filtered": {
            "query": {
                "match_all": {}
            },
            "filter": {
                "geo_shape": {
                    "location": {
                        "shape": {
                            "type": "envelope",
                            "coordinates" : [[13.0, 53.0], [14.0, 52.0]]
                        }
                    }
                }
            }
        }
    }
}
--------------------------------------------------

[float]
===== 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:

[source,js]
--------------------------------------------------
{
    "filtered": {
        "query": {
            "match_all": {}
        },
        "filter": {
            "geo_shape": {
                "location": {
                    "indexed_shape": {
                        "id": "DEU",
                        "type": "countries",
                        "index": "shapes",
                        "path": "location"
                    }
                }
            }
        }
    }
}
--------------------------------------------------