Elasticsearch Geo Bounding Box Query

The Geo Bounding Box Query in Elasticsearch allows you to find documents with geo-points that fall within a specified rectangular area. This query is particularly useful for geospatial searches where you need to filter results based on a geographical region defined by top-left and bottom-right coordinates.

Syntax

The basic syntax for a Geo Bounding Box Query is as follows:

GET /_search
{
  "query": {
    "geo_bounding_box": {
      "FIELD": {
        "top_left": {
          "lat": TOP_LEFT_LAT,
          "lon": TOP_LEFT_LON
        },
        "bottom_right": {
          "lat": BOTTOM_RIGHT_LAT,
          "lon": BOTTOM_RIGHT_LON
        }
      }
    }
  }
}

For more details, refer to the official Elasticsearch documentation.

Example Query

Here's an example query that searches for documents with locations within a bounding box:

GET /my_locations/_search
{
  "query": {
    "geo_bounding_box": {
      "location": {
        "top_left": {
          "lat": 40.73,
          "lon": -74.1
        },
        "bottom_right": {
          "lat": 40.01,
          "lon": -71.12
        }
      }
    }
  }
}

This query will return all documents in the my_locations index where the location field contains a geo-point within the specified bounding box.

Common Issues

1. Incorrect coordinate order: Remember that Elasticsearch uses the format [longitude, latitude] for geo-points, which is the opposite of the common [latitude, longitude] format.
2. Out-of-range coordinates: Ensure that latitude values are between -90 and 90, and longitude values are between -180 and 180.
3. Performance on large datasets: For very large datasets, consider using a geo-hash grid aggregation in combination with this query for better performance.

Best Practices

1. Use the validation_method parameter to control how Elasticsearch handles invalid geo-points.
2. Consider using the type parameter to specify alternative formats for defining the bounding box, such as "vertices" or "wkt".
3. For complex shapes or more precise geospatial queries, consider using the Geo-shape query instead.

Frequently Asked Questions

Q: Can I use the Geo Bounding Box Query with geo-shapes?
A: No, the Geo Bounding Box Query is specifically for geo-points. For geo-shapes, you should use the Geo-shape Query instead.

Q: How does the Geo Bounding Box Query handle the dateline and poles?
A: The query automatically handles dateline and pole wrapping. You can specify a bounding box that crosses the dateline by providing a top-left longitude greater than the bottom-right longitude.

Q: Is there a way to exclude the boundaries of the bounding box?
A: Yes, you can use the type parameter with a value of "indexed" to exclude the boundaries. This treats points on the boundary as outside the bounding box.

Q: Can I use this query with geo-point fields that contain multiple values?
A: Yes, if a document's geo-point field contains multiple values, the document will match if any of those points fall within the bounding box.

Q: How does this query perform compared to other geo queries?
A: The Geo Bounding Box Query is generally very efficient, especially for large rectangular areas. However, for more complex shapes or very small areas, other geo queries like the Geo-shape Query might be more appropriate.