Geo searchdev
A location is a typed geo_point, and a geo query (a box, a radius, or a set
of polygons) can go anywhere another query can: as the main query, as a
non-scoring filter on text or vector retrieval, or as one boolean clause
among several. “Coffee within five kilometers” is a text query with a
distance filter beside it, evaluated as one query with no post-filter stage.
Define a point field
Section titled “Define a point field”A field whose name ends in _p (single point) or _ps (several points)
uses a default template with the points index on, so location_p needs no
definition. Any other name needs an explicit schema definition:
{ "fields": { "location": {"type":"geo_point","index":"range"} }}column defaults to true. index: "range" builds a two-dimensional points
index for boxes and circles. If it is omitted, the same queries remain correct
and scan the point column instead. The indexed and scan paths return the
same results; only the cost differs.
Geo fields reject stored: true: points are kept in the field’s column for
queries and sorting, not as stored values.
For a document with several locations, set multi: true:
{"type":"geo_point","index":"range","multi":true}Point formats
Section titled “Point formats”The canonical point value is [lon, lat], the same coordinate order used by
GeoJSON:
{ "docs": [ {"id":"nyc","name_s":"New York","description_t":"coffee and bagels","location":[-74.0060,40.7128]}, {"id":"london","name_s":"London","description_t":"tea and coffee","location":[-0.1278,51.5074]} ], "commit": {}}Longitude must be within [-180,180] and latitude within [-90,90]. Luxir
quantizes each coordinate into a 32-bit grid, roughly centimeter resolution.
The same point can be written in any of these forms, over HTTP JSON and gRPC alike:
| Form | Example | Notes |
|---|---|---|
| Array | [-74.0060, 40.7128] |
[lon, lat] |
| Object | {"lat": 40.7128, "lon": -74.0060} |
values may be numeric strings |
| GeoJSON | {"type": "Point", "coordinates": [-74.0060, 40.7128]} |
[lon, lat] |
| String | "40.7128,-74.0060" |
latitude first, as in Elasticsearch |
| WKT | "POINT (-74.0060 40.7128)" |
longitude first; case-insensitive |
| Geohash | "dr5regw3p" |
1 to 12 characters; decoded to the centre of the cell |
Keep the order straight: arrays, GeoJSON and WKT put longitude first, while
the "lat,lon" string puts latitude first. A string with no comma that is
not WKT is read as a geohash. For example, a coordinate sent as the bare
string "40" becomes a coarse geohash cell, not a number.
A multi-valued field, such as one named by the _ps template, takes an
array of points in any mix of forms:
{"id":"tour","name_s":"City tour","stops_ps":[[-74.0060,40.7128],"51.5074,-0.1278","u4pruydqqvj"]}An array whose elements are all numbers is always one point, so
[-74.0060, 40.7128] sent to a multi-valued field is one point, not two.
Any other array lists points, one per element, and null elements are
skipped. A single-valued field also accepts a one-element array of points,
and rejects a document that gives it more than one.
Malformed points and altitude
Section titled “Malformed points and altitude”By default a value that is not a valid point, such as an unreadable string, a coordinate out of range, or an array of the wrong length, fails the whole document with an error naming the field. Two field properties relax this:
{"type":"geo_point","index":"range","ignore_malformed":true,"ignore_z_value":true}ignore_malformed: trueskips a malformed point and indexes the rest of the document. In a multi-valued field only the bad points are skipped. Skipped values are not reported in the update response.- A third coordinate (
[lon, lat, z],"lat,lon,z",POINT Z (lon lat z)) is an altitude. By defaultignore_z_value: trueaccepts the point and drops the altitude. Setignore_z_value: falseto reject a third coordinate. Altitude is never indexed.
ignore_malformed defaults to false; ignore_z_value defaults to true.
An in-range longitude/latitude swap cannot be detected. Rejected points name
the recognized form and interpreted lon and lat when both can be read.
Templates and parent inheritance carry these options like other
properties. They belong to the logical field, like multi: a
variant of a geo field follows the primary’s
settings and cannot set its own.
Bounding boxes
Section titled “Bounding boxes”geo_box uses named scalar bounds so latitude and longitude cannot be confused:
{ "query": { "geo_box": { "field": "location", "min_lat": 40.0, "max_lat": 42.0, "min_lon": -75.0, "max_lon": -72.0 } }, "fields": ["id","name_s"], "count_limit": -2}All edges are inclusive after the same coordinate quantization used at ingest.
min_lat must not exceed max_lat. If min_lon is greater than max_lon,
the box intentionally crosses the international date line:
{ "geo_box": { "field":"location", "min_lat":-20, "max_lat":20, "min_lon":170, "max_lon":-170 }}That matches the band from 170 degrees east through 180/-180 to 170 degrees west.
Distance queries
Section titled “Distance queries”geo_distance matches points within an inclusive radius in meters. Query
centers use separate lat and lon keys:
{ "query": { "geo_distance": { "field":"location", "lat":40.7128, "lon":-74.0060, "radius_meters":50000 } }, "fields":["id","name_s"], "count_limit":-2}Distances use a great-circle calculation over the mean Earth radius. A radius must be finite and non-negative. For a multi-valued field, a document matches when any point is inside the circle, and the document is returned once.
Polygon queries
Section titled “Polygon queries”geo_polygon matches points inside any of its polygons. Each polygon has
an outer ring and optional holes, and vertices use named lat and lon
keys. This query matches London; New York lies in the first polygon’s hole:
{ "query": { "geo_polygon": { "field":"location", "polygons":[ { "points":[ {"lat":40.0,"lon":-75.0}, {"lat":42.0,"lon":-75.0}, {"lat":42.0,"lon":-72.0}, {"lat":40.0,"lon":-72.0} ], "holes":[ {"points":[ {"lat":40.5,"lon":-74.5}, {"lat":41.0,"lon":-74.5}, {"lat":41.0,"lon":-73.5}, {"lat":40.5,"lon":-73.5} ]} ] }, { "points":[ {"lat":51.0,"lon":-1.0}, {"lat":52.0,"lon":-1.0}, {"lat":52.0,"lon":1.0}, {"lat":51.0,"lon":1.0} ] } ] } }, "fields":["id","name_s"]}{"docs":[{"id":"london","name_s":"London"}]}| Key | Meaning |
|---|---|
field |
The geo_point field. |
polygons |
One or more polygons. A point matches when it is inside any of them. |
points |
A polygon’s outer ring, at least three distinct vertices. |
holes |
Optional rings, each {"points":[...]}, cut out of their own polygon. |
A ring lists its vertices in order, and the last connects back to the first; repeating the first vertex at the end is allowed. A point is inside a polygon when it is inside the outer ring and inside none of that polygon’s holes, each ring by the even-odd rule, so a self-intersecting ring still has a defined inside. A hole cuts only its own polygon: a point in one polygon’s hole still matches through another polygon that covers it.
Edges are straight lines in latitude and longitude, as in Lucene’s point
polygon queries. A polygon cannot cross the date line; split it into two
polygons of the same query. A point exactly on an edge may match either way.
With index: "range" the points index skips whole regions outside every
polygon and accepts whole regions inside one. A point check does not test
every edge, so polygons with many vertices, such as administrative
boundaries, stay practical.
Combine place with relevance
Section titled “Combine place with relevance”Geo queries are constant-scoring when used as queries and non-scoring when used as filters. The usual pattern is a text query with a geo filter, so text relevance is unaffected:
{ "query": {"match":{"description_t":"coffee"}}, "filter": [ { "geo_distance": { "field":"location", "lat":40.7128, "lon":-74.0060, "radius_meters":5000 } } ], "fields":["id","name_s","description_t"]}{ "docs": [ { "id": "nyc", "name_s": "New York", "description_t": "coffee and bagels" } ]}The geo constraint participates in the same prepared execution as the lexical query. A selective surrounding domain can drive point verification; a broader domain can be driven by the points index.
Return points
Section titled “Return points”A geo field in fields returns its points in the canonical ingest shape, so
a returned value indexes back as the same points. A single-valued field
returns [lon, lat]. A multi-valued field returns a list of points,
[[lon, lat], ...], even for a document with one point:
{"query":"id:(nyc tour)","fields":["id","location","stops_ps"]}{ "docs": [ {"id":"nyc","location":[-74.00600004941225,40.712799984030426]}, { "id":"tour", "stops_ps":[ [-74.00600004941225,40.712799984030426], [-0.12780005112290382,51.50739999487996], [10.407439693808556,57.64911063015461] ] } ]}The values are the quantized grid points, so they differ from the input in
roughly the eighth decimal place, and a geohash comes back as the centre of
its cell. A wildcard or empty fields selection includes geo fields. On the
gRPC API a geo field is a col_val column holding the same Val shapes the
ingest API reads: an arr_d pair, or an arr of pairs for a multi-valued
field.
Limits
Section titled “Limits”- There is no distance sort field. Sort by distance with the sort expression
geo_distance(field, lat, lon), in meters. - The query does not emit the computed distance as a result field.
- Polygons cannot cross the date line.
- Polygon vertices are
{"lat","lon"}objects; GeoJSONPolygonandMultiPolygoncoordinates are not accepted as query input yet.