Class LatLonPoint
- All Implemented Interfaces:
IndexableField
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:
-
Nested Class Summary
Nested classes/interfaces inherited from class org.apache.lucene.document.Field
Field.Store -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intLatLonPoint is encoded as integer values so number of bytes is 4static final FieldTypeType for an indexed LatLonPointFields inherited from class org.apache.lucene.document.Field
fieldsData, name, type -
Constructor Summary
ConstructorsConstructorDescriptionLatLonPoint(String name, double latitude, double longitude) Creates a new LatLonPoint with the specified latitude and longitude -
Method Summary
Modifier and TypeMethodDescriptionstatic TopFieldDocsnearest(IndexSearcher searcher, String field, double latitude, double longitude, int n) Finds thennearest indexed points to the provided point, according to Haversine distance.static QuerynewBoxQuery(String field, double minLatitude, double maxLatitude, double minLongitude, double maxLongitude) Create a query for matching a bounding box.static QuerynewDistanceFeatureQuery(String field, float weight, double originLat, double originLon, double pivotDistanceMeters) Given a field that indexes point values into aLatLonPointand doc values intoLatLonDocValuesField, this returns a query that scores documents based on their haversine distance in meters to(originLat, originLon):score = weight * pivotDistanceMeters / (pivotDistanceMeters + distance), ie.static QuerynewDistanceQuery(String field, double latitude, double longitude, double radiusMeters) Create a query for matching points within the specified distance of the supplied location.static QuerynewGeometryQuery(String field, ShapeField.QueryRelation queryRelation, LatLonGeometry... latLonGeometries) Create a query for matching one or more geometries against the providedShapeField.QueryRelation.static QuerynewPolygonQuery(String field, Polygon... polygons) Create a query for matching one or more polygons.voidsetLocationValue(double latitude, double longitude) Change the values of this fieldtoString()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
-
Field Details
-
BYTES
public static final int BYTESLatLonPoint is encoded as integer values so number of bytes is 4- See Also:
-
TYPE
Type for an indexed LatLonPointEach point stores two dimensions with 4 bytes per dimension.
-
-
Constructor Details
-
LatLonPoint
Creates a new LatLonPoint with the specified latitude and longitude- Parameters:
name- field namelatitude- 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
Description copied from class:FieldPrints a Field for human consumption. -
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- iffieldis 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- iffieldis null, location has invalid coordinates, or radius is invalid.
-
newPolygonQuery
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- iffieldis null,polygonsis 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 providedShapeField.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- iffieldis null,queryRelationis null,latLonGeometriesis 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 aLatLonPointand doc values intoLatLonDocValuesField, 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 toweightwhen the document's value is equal to(originLat, originLon)and is equal toweight/2when the document's value is distant ofpivotDistanceMetersfrom(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 aBooleanClause.Occur.SHOULDclause of aBooleanQuery. -
nearest
public static TopFieldDocs nearest(IndexSearcher searcher, String field, double latitude, double longitude, int n) throws IOException Finds thennearest indexed points to the provided point, according to Haversine distance.This is functionally equivalent to running
MatchAllDocsQuerywith aLatLonDocValuesField.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
FieldDocfor 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
FieldDocis the distance in meters - Throws:
IllegalArgumentException- iffieldorsearcheris null, or iflatitude,longitudeornare out-of-boundsIOException- if an IOException occurs while finding the points.
-