org.apache.lucene.document

Class LatLonDocValuesField

java.lang.Object

org.apache.lucene.document.Field

org.apache.lucene.document.LatLonDocValuesField

All Implemented Interfaces:

IndexableField

public class LatLonDocValuesField
extends Field

An per-document location field.

Sorting by distance is efficient. Multiple values for the same field in one document is allowed.

This field defines static factory methods for common operations:

• newDistanceSort() for ordering documents by distance from a specified location.

If you also need query operations, you should add a separate LatLonPoint 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:

LatLonPoint

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 FieldType	TYPE Type for a LatLonDocValuesField

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

boost, fieldsData, name, tokenStream, type

Constructor Summary

Constructors

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

Method Summary

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 using doc values.
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 SortField	newDistanceSort(String field, double latitude, double longitude) Creates a SortField for sorting by distance from a location.
void	setLocationValue(double latitude, double longitude) Change the values of this field
String	toString()

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

binaryValue, boost, fieldType, name, numericValue, readerValue, setBoost, 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

TYPE

public static final FieldType TYPE

Type for a LatLonDocValuesField

Each value stores a 64-bit long where the upper 32 bits are the encoded latitude, and the lower 32 bits are the encoded longitude.

See Also:

GeoEncodingUtils.decodeLatitude(int), GeoEncodingUtils.decodeLongitude(int)

Constructor Detail

LatLonDocValuesField

public LatLonDocValuesField(String name,
                            double latitude,
                            double longitude)

Creates a new LatLonDocValuesField 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()

Overrides:

toString in class Field

newDistanceSort

public static SortField newDistanceSort(String field,
                                        double latitude,
                                        double longitude)

Creates a SortField for sorting by distance from a location.

This sort orders documents by ascending distance from the location. The value returned in FieldDoc for the hits contains a Double instance with the distance in meters.

If a document is missing the field, then by default it is treated as having Double.POSITIVE_INFINITY distance (missing values sort last).

If a document contains multiple values for the field, the closest distance to the location is used.

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.

Returns:

SortField ordering documents by distance

Throws:

IllegalArgumentException - if field is null or location has invalid coordinates.

newBoxQuery

public static Query newBoxQuery(String field,
                                double minLatitude,
                                double maxLatitude,
                                double minLongitude,
                                double maxLongitude)

Create a query for matching a bounding box using doc values. This query is usually slow as it does not use an index structure and needs to verify documents one-by-one in order to know whether they match. It is best used wrapped in an IndexOrDocValuesQuery alongside a LatLonPoint.newBoxQuery(java.lang.String, double, double, double, double).

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. This query is usually slow as it does not use an index structure and needs to verify documents one-by-one in order to know whether they match. It is best used wrapped in an IndexOrDocValuesQuery alongside a LatLonPoint.newDistanceQuery(java.lang.String, double, double, double).

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.