elasticsearch/elasticsearch — pull request #3201 by chilling (2013-06-18 14:13:34+00:00)
Title: GeoHash Filter

Previous versions of the `GeoPointFieldMapper` just stored the actual geohash
of a point. This commit changes the behavior of storing geohashes by storing
the geohash and *all* its prefixes in decreasing order in the same field. To
enable this functionality the option `geohash_prefix` must be set in the mapping.

This behavior allows to filter `GeoPoints` by their *geohashes*. Basically a
geohash prefix is defined by the filter and all geohashes that match this
prefix will be returned. The `neighbors` flag allows to filter geohashes
that surround the given geohash cell. In general the neighborhood of a
geohash is defined by its eight adjacent cells.

To enable this, the type of filtered fields must be `geo_point` with `geohashes`
and `geohash_prefix` enabled.

For example:
```
curl -XPUT 'http://127.0.0.1:9200/locations/?pretty=true' -d '{
"mappings" : {
"location": {
"properties": {
"pin": {
"type": "geo_point",
"geohash": true,
"geohash_prefix": true
}
}
}
}
}'
```
This example defines a mapping for a type `location` in an index `locations`
with a field `pin`. The option `geohash` arranges storing the geohash of
the `pin` field.

To filter the results by the geohash a `geohash_bbox` must to be defined.
For example
```
curl -XGET 'http://127.0.0.1:9200/locations/_search?pretty=true' -d '{
"query": {
"match_all":{}
},
"filter": {
"geohash_bbox": {
"field": "pin",
"geohash": "u30",
"neighbors": true
}
}
}'

```
This filter will match all geohashes that start with one of the following
prefixes: `u30`, `u1r`, `u32`, `u33`, `u1p`, `u31`, `u0z`, `u2b` and `u2c`.

Internally the `GeoHashFilter` is either a simple `TermFilter`, in case no
neighbors should be filtered or a `BooleanFilter` combining the `TermFilters`
of the geohash and all its neighbors.

Closes #2778