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 and Description
    --- | ---
    `static int` | `BYTES` LatLonPoint is encoded as integer values so number of bytes is 4
    `static FieldType` | `TYPE` Type for an indexed LatLonPoint

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

      `fieldsData, name, tokenStream, type`

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, stringValue, tokenStream, tokenStreamValue`

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

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

- - ### Field Detail

    - #### 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 Detail

    - #### 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 Detail

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

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.