LatLonPoint (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.document, class: LatLonPoint

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:

- `newBoxQuery()` for matching points within a bounding box.
- `newDistanceQuery()` for matching points within a specified distance.
- `newPolygonQuery()` for matching points within an arbitrary polygon.
- `newGeometryQuery()` for matching points within an arbitrary geometry collection.

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:
  - `PointValues`
  - `LatLonDocValuesField`

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.document.Field

  `Field.Store`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BYTES`
  LatLonPoint is encoded as integer values so number of bytes is 4
  `static final FieldType`
  `TYPE`
  Type for an indexed LatLonPoint

  ### Fields inherited from class org.apache.lucene.document.Field

  `fieldsData, name, type`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LatLonPoint(String name, double latitude, double longitude)`
  Creates a new LatLonPoint with the specified latitude and longitude

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static TopFieldDocs`
  `nearest(IndexSearcher searcher, String field, double latitude, double longitude, int n)`
  Finds the `n` nearest indexed points to the provided point, according to Haversine distance.
  `static Query`
  `newBoxQuery(String field, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude)`
  Create a query for matching a bounding box.
  `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.
  `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.
  `static Query`
  `newGeometryQuery(String field, ShapeField.QueryRelation queryRelation, LatLonGeometry... latLonGeometries)`
  Create a query for matching one or more geometries against the provided `ShapeField.QueryRelation`.
  `static Query`
  `newPolygonQuery(String field, Polygon... polygons)`
  Create a query for matching one or more polygons.
  `void`
  `setLocationValue(double latitude, double longitude)`
  Change the values of this field
  `String`
  `toString()`
  Prints a Field for human consumption.

  ### Methods inherited from class org.apache.lucene.document.Field

  `binaryValue, fieldType, getCharSequenceValue, invertableType, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, storedValue, stringValue, tokenStream, tokenStreamValue`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### BYTES

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

  - ### 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:
      - `Polygon`

  - ### 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:
      - `LatLonGeometry`

  - ### 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`.

  - ### nearest

    public static TopFieldDocs nearest(IndexSearcher searcher, String field, double latitude, double longitude, int n) throws IOException
    Finds the `n` nearest indexed points to the provided point, according to Haversine distance.

    This is functionally equivalent to running `MatchAllDocsQuery` with a `LatLonDocValuesField.newDistanceSort(java.lang.String, double, double)`, but is far more efficient since it takes advantage of properties the indexed BKD tree. Multi-valued fields are currently not de-duplicated, so if a document had multiple instances of the specified field that make it into the top n, that document will appear more than once.

    Documents are ordered by ascending distance from the location. The value returned in `FieldDoc` for the hits contains a Double instance with the distance in meters.

    Parameters:
      `searcher` - IndexSearcher to find nearest points from.
      `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.
      `n` - the number of nearest neighbors to retrieve.
    Returns:
      TopFieldDocs containing documents ordered by distance, where the field value for each `FieldDoc` is the distance in meters
    Throws:
      `IllegalArgumentException` - if `field` or `searcher` is null, or if `latitude`, `longitude` or `n` are out-of-bounds
      `IOException` - if an IOException occurs while finding the points.