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