2013-08-28 19:24:34 -04:00
|
|
|
[[search-facets-geo-distance-facet]]
|
|
|
|
=== Geo Distance Facets
|
|
|
|
|
2014-06-12 10:38:10 -04:00
|
|
|
include::deprecated.asciidoc[]
|
|
|
|
|
2013-08-28 19:24:34 -04:00
|
|
|
The geo_distance facet is a facet providing information for ranges of
|
|
|
|
distances from a provided geo_point including count of the number of
|
|
|
|
hits that fall within each range, and aggregation information (like
|
|
|
|
total).
|
|
|
|
|
|
|
|
Assuming the following sample doc:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"pin" : {
|
|
|
|
"location" : {
|
|
|
|
"lat" : 40.12,
|
|
|
|
"lon" : -71.34
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
Here is an example that create a `geo_distance` facet from a
|
|
|
|
`pin.location` of 40,-70, and a set of ranges:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"query" : {
|
|
|
|
"match_all" : {}
|
|
|
|
},
|
|
|
|
"facets" : {
|
|
|
|
"geo1" : {
|
|
|
|
"geo_distance" : {
|
|
|
|
"pin.location" : {
|
|
|
|
"lat" : 40,
|
|
|
|
"lon" : -70
|
|
|
|
},
|
|
|
|
"ranges" : [
|
|
|
|
{ "to" : 10 },
|
|
|
|
{ "from" : 10, "to" : 20 },
|
|
|
|
{ "from" : 20, "to" : 100 },
|
|
|
|
{ "from" : 100 }
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
==== Accepted Formats
|
|
|
|
|
|
|
|
In much the same way the geo_point type can accept different
|
|
|
|
representation of the geo point, the filter can accept it as well:
|
|
|
|
|
|
|
|
===== Lat Lon As Properties
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"query" : {
|
|
|
|
"match_all" : {}
|
|
|
|
},
|
|
|
|
"facets" : {
|
|
|
|
"geo1" : {
|
|
|
|
"geo_distance" : {
|
|
|
|
"pin.location" : {
|
|
|
|
"lat" : 40,
|
|
|
|
"lon" : -70
|
|
|
|
},
|
|
|
|
"ranges" : [
|
|
|
|
{ "to" : 10 },
|
|
|
|
{ "from" : 10, "to" : 20 },
|
|
|
|
{ "from" : 20, "to" : 100 },
|
|
|
|
{ "from" : 100 }
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
===== Lat Lon As Array
|
|
|
|
|
|
|
|
Format in `[lon, lat]`, note, the order of lon/lat here in order to
|
|
|
|
conform with http://geojson.org/[GeoJSON].
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"query" : {
|
|
|
|
"match_all" : {}
|
|
|
|
},
|
|
|
|
"facets" : {
|
|
|
|
"geo1" : {
|
|
|
|
"geo_distance" : {
|
|
|
|
"pin.location" : [40, -70],
|
|
|
|
"ranges" : [
|
|
|
|
{ "to" : 10 },
|
|
|
|
{ "from" : 10, "to" : 20 },
|
|
|
|
{ "from" : 20, "to" : 100 },
|
|
|
|
{ "from" : 100 }
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
===== Lat Lon As String
|
|
|
|
|
|
|
|
Format in `lat,lon`.
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"query" : {
|
|
|
|
"match_all" : {}
|
|
|
|
},
|
|
|
|
"facets" : {
|
|
|
|
"geo1" : {
|
|
|
|
"geo_distance" : {
|
|
|
|
"pin.location" : "40, -70",
|
|
|
|
"ranges" : [
|
|
|
|
{ "to" : 10 },
|
|
|
|
{ "from" : 10, "to" : 20 },
|
|
|
|
{ "from" : 20, "to" : 100 },
|
|
|
|
{ "from" : 100 }
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
===== Geohash
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"query" : {
|
|
|
|
"match_all" : {}
|
|
|
|
},
|
|
|
|
"facets" : {
|
|
|
|
"geo1" : {
|
|
|
|
"geo_distance" : {
|
|
|
|
"pin.location" : "drm3btev3e86",
|
|
|
|
"ranges" : [
|
|
|
|
{ "to" : 10 },
|
|
|
|
{ "from" : 10, "to" : 20 },
|
|
|
|
{ "from" : 20, "to" : 100 },
|
|
|
|
{ "from" : 100 }
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
==== Ranges
|
|
|
|
|
|
|
|
When a `to` or `from` are not set, they are assumed to be unbounded.
|
|
|
|
Ranges are allowed to overlap, basically, each range is treated by
|
|
|
|
itself.
|
|
|
|
|
|
|
|
==== Options
|
|
|
|
|
|
|
|
[cols="<,<",options="header",]
|
|
|
|
|=======================================================================
|
|
|
|
|Option |Description
|
|
|
|
|`unit` |The unit the ranges are provided in. Defaults to `km`. Can also
|
2013-12-18 23:52:33 -05:00
|
|
|
be `mi`, `miles`, `in`, `inch`, `yd`, `yards`, `ft`, `feet`, `kilometers`, `mm`, `millimeters`, `cm`, `centimeters`, `m` or `meters`.
|
2013-08-28 19:24:34 -04:00
|
|
|
|
|
|
|
|`distance_type` |How to compute the distance. Can either be `arc`
|
2013-12-18 00:58:22 -05:00
|
|
|
(better precision), `sloppy_arc` (faster) or `plane` (fastest). Defaults to `sloppy_arc`.
|
2013-08-28 19:24:34 -04:00
|
|
|
|=======================================================================
|
|
|
|
|
|
|
|
==== Value Options
|
|
|
|
|
|
|
|
On top of the count of hits falling within each range, aggregated data
|
|
|
|
can be provided (total) as well. By default, the aggregated data will
|
|
|
|
simply use the distance calculated, but the value can be extracted
|
|
|
|
either using a different numeric field, or a script. Here is an example
|
|
|
|
of using a different numeric field:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"query" : {
|
|
|
|
"match_all" : {}
|
|
|
|
},
|
|
|
|
"facets" : {
|
|
|
|
"geo1" : {
|
|
|
|
"geo_distance" : {
|
|
|
|
"pin.location" : "drm3btev3e86",
|
|
|
|
"value_field" : "num1",
|
|
|
|
"ranges" : [
|
|
|
|
{ "to" : 10 },
|
|
|
|
{ "from" : 10, "to" : 20 },
|
|
|
|
{ "from" : 20, "to" : 100 },
|
|
|
|
{ "from" : 100 }
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
And here is an example of using a script:
|
|
|
|
|
|
|
|
[source,js]
|
|
|
|
--------------------------------------------------
|
|
|
|
{
|
|
|
|
"query" : {
|
|
|
|
"match_all" : {}
|
|
|
|
},
|
|
|
|
"facets" : {
|
|
|
|
"geo1" : {
|
|
|
|
"geo_distance" : {
|
|
|
|
"pin.location" : "drm3btev3e86",
|
|
|
|
"value_script" : "doc['num1'].value * factor",
|
|
|
|
"params" : {
|
|
|
|
"factor" : 5
|
|
|
|
}
|
|
|
|
"ranges" : [
|
|
|
|
{ "to" : 10 },
|
|
|
|
{ "from" : 10, "to" : 20 },
|
|
|
|
{ "from" : 20, "to" : 100 },
|
|
|
|
{ "from" : 100 }
|
|
|
|
]
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
--------------------------------------------------
|
|
|
|
|
|
|
|
Note the params option, allowing to pass parameters to the script
|
|
|
|
(resulting in faster script execution instead of providing the values
|
|
|
|
within the script each time).
|
|
|
|
|
|
|
|
.`geo_point` Type
|
|
|
|
[NOTE]
|
|
|
|
--
|
|
|
|
The facet *requires* the `geo_point` type to be set on the relevant
|
|
|
|
field.
|
|
|
|
--
|
|
|
|
|
|
|
|
.Multi Location Per Document
|
|
|
|
[NOTE]
|
|
|
|
--
|
|
|
|
The facet can work with multiple locations per document.
|
2013-09-17 08:20:26 -04:00
|
|
|
--
|