Package org.apache.lucene.document

Class LatLonPoint

java.lang.Object
org.apache.lucene.document.Field
org.apache.lucene.document.LatLonPoint
All Implemented Interfaces:
IndexableField
public class LatLonPoint extends Field
An indexed location field.

Finding all documents within a range at search time is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for common operations:

If you also need per-document operations such as sort by distance, add a separate LatLonDocValuesField instance. If you also need to store the value, you should add a separate StoredField instance.

WARNING: Values are indexed with some loss of precision from the original double values (4.190951585769653E-8 for the latitude component and 8.381903171539307E-8 for longitude).

See Also:

  • Field Details

    • BYTES

      public static final int BYTES
      LatLonPoint is encoded as integer values so number of bytes is 4
      See Also:

    • TYPE

      public static final FieldType TYPE
      Type for an indexed LatLonPoint

      Each point stores two dimensions with 4 bytes per dimension.

  • Constructor Details

    • LatLonPoint

      public LatLonPoint(String name, double latitude, double longitude)
      Creates a new LatLonPoint with the specified latitude and longitude
      Parameters:
      name - field name
      latitude - latitude value: must be within standard +/-90 coordinate bounds.
      longitude - longitude value: must be within standard +/-180 coordinate bounds.
      Throws:
      IllegalArgumentException - if the field name is null or latitude or longitude are out of bounds

  • Method Details

    • setLocationValue

      public void setLocationValue(double latitude, double longitude)
      Change the values of this field
      Parameters:
      latitude - latitude value: must be within standard +/-90 coordinate bounds.
      longitude - longitude value: must be within standard +/-180 coordinate bounds.
      Throws:
      IllegalArgumentException - if latitude or longitude are out of bounds

    • toString

      public String toString()
      Description copied from class: Field
      Prints a Field for human consumption.
      Overrides:
      toString in class Field

    • newBoxQuery

      public static Query newBoxQuery(String field, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude)
      Create a query for matching a bounding box.

      The box may cross over the dateline.

      Parameters:
      field - field name. must not be null.
      minLatitude - latitude lower bound: must be within standard +/-90 coordinate bounds.
      maxLatitude - latitude upper bound: must be within standard +/-90 coordinate bounds.
      minLongitude - longitude lower bound: must be within standard +/-180 coordinate bounds.
      maxLongitude - longitude upper bound: must be within standard +/-180 coordinate bounds.
      Returns:
      query matching points within this box
      Throws:
      IllegalArgumentException - if field is null, or the box has invalid coordinates.

    • newDistanceQuery

      public static Query newDistanceQuery(String field, double latitude, double longitude, double radiusMeters)
      Create a query for matching points within the specified distance of the supplied location.
      Parameters:
      field - field name. must not be null.
      latitude - latitude at the center: must be within standard +/-90 coordinate bounds.
      longitude - longitude at the center: must be within standard +/-180 coordinate bounds.
      radiusMeters - maximum distance from the center in meters: must be non-negative and finite.
      Returns:
      query matching points within this distance
      Throws:
      IllegalArgumentException - if field is null, location has invalid coordinates, or radius is invalid.

    • newPolygonQuery

      public static Query newPolygonQuery(String field, Polygon... polygons)
      Create a query for matching one or more polygons.
      Parameters:
      field - field name. must not be null.
      polygons - array of polygons. must not be null or empty
      Returns:
      query matching points within this polygon
      Throws:
      IllegalArgumentException - if field is null, polygons is null or empty
      See Also:

    • newGeometryQuery

      public static Query newGeometryQuery(String field, ShapeField.QueryRelation queryRelation, LatLonGeometry... latLonGeometries)
      Create a query for matching one or more geometries against the provided ShapeField.QueryRelation. Line geometries are not supported for WITHIN relationship.
      Parameters:
      field - field name. must not be null.
      queryRelation - The relation the points needs to satisfy with the provided geometries, must not be null.
      latLonGeometries - array of LatLonGeometries. must not be null or empty.
      Returns:
      query matching points within at least one geometry.
      Throws:
      IllegalArgumentException - if field is null, queryRelation is null, latLonGeometries is null, empty or contain a null.
      See Also:

    • newDistanceFeatureQuery

      public static Query newDistanceFeatureQuery(String field, float weight, double originLat, double originLon, double pivotDistanceMeters)
      Given a field that indexes point values into a LatLonPoint and doc values into LatLonDocValuesField, this returns a query that scores documents based on their haversine distance in meters to (originLat, originLon): score = weight * pivotDistanceMeters / (pivotDistanceMeters + distance), ie. score is in the [0, weight] range, is equal to weight when the document's value is equal to (originLat, originLon) and is equal to weight/2 when the document's value is distant of pivotDistanceMeters from (originLat, originLon). In case of multi-valued fields, only the closest point to (originLat, originLon) will be considered. This query is typically useful to boost results based on distance by adding this query to a BooleanClause.Occur.SHOULD clause of a BooleanQuery.