org.apache.lucene.document.LatLonDocValuesField Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.lucene.document;
import static org.apache.lucene.geo.GeoEncodingUtils.decodeLatitude;
import static org.apache.lucene.geo.GeoEncodingUtils.decodeLongitude;
import static org.apache.lucene.geo.GeoEncodingUtils.encodeLatitude;
import static org.apache.lucene.geo.GeoEncodingUtils.encodeLongitude;
import org.apache.lucene.geo.Circle;
import org.apache.lucene.geo.LatLonGeometry;
import org.apache.lucene.geo.Point;
import org.apache.lucene.geo.Polygon;
import org.apache.lucene.geo.Rectangle;
import org.apache.lucene.index.DocValuesType;
import org.apache.lucene.index.FieldInfo;
import org.apache.lucene.search.FieldDoc;
import org.apache.lucene.search.IndexOrDocValuesQuery;
import org.apache.lucene.search.MatchNoDocsQuery;
import org.apache.lucene.search.Query;
import org.apache.lucene.search.SortField;
/**
* 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:
*
*
* - {@link #newDistanceSort newDistanceSort()} for ordering documents by distance from a
* specified location.
*
*
* If you also need query operations, you should add a separate {@link LatLonPoint} instance. If
* you also need to store the value, you should add a separate {@link StoredField} instance.
*
*
WARNING: Values are indexed with some loss of precision from the original {@code
* double} values (4.190951585769653E-8 for the latitude component and 8.381903171539307E-8 for
* longitude).
*
* @see LatLonPoint
*/
public class LatLonDocValuesField extends Field {
/**
* 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 org.apache.lucene.geo.GeoEncodingUtils#decodeLatitude(int)
* @see org.apache.lucene.geo.GeoEncodingUtils#decodeLongitude(int)
*/
public static final FieldType TYPE = new FieldType();
static {
TYPE.setDocValuesType(DocValuesType.SORTED_NUMERIC);
TYPE.freeze();
}
/**
* Creates a new LatLonDocValuesField with the specified latitude and longitude
*
* @param name field name
* @param latitude latitude value: must be within standard +/-90 coordinate bounds.
* @param 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
*/
public LatLonDocValuesField(String name, double latitude, double longitude) {
super(name, TYPE);
setLocationValue(latitude, longitude);
}
/**
* Change the values of this field
*
* @param latitude latitude value: must be within standard +/-90 coordinate bounds.
* @param longitude longitude value: must be within standard +/-180 coordinate bounds.
* @throws IllegalArgumentException if latitude or longitude are out of bounds
*/
public void setLocationValue(double latitude, double longitude) {
int latitudeEncoded = encodeLatitude(latitude);
int longitudeEncoded = encodeLongitude(longitude);
fieldsData = Long.valueOf((((long) latitudeEncoded) << 32) | (longitudeEncoded & 0xFFFFFFFFL));
}
/**
* helper: checks a fieldinfo and throws exception if its definitely not a LatLonDocValuesField
*/
static void checkCompatible(FieldInfo fieldInfo) {
// dv properties could be "unset", if you e.g. used only StoredField with this same name in the
// segment.
if (fieldInfo.getDocValuesType() != DocValuesType.NONE
&& fieldInfo.getDocValuesType() != TYPE.docValuesType()) {
throw new IllegalArgumentException(
"field=\""
+ fieldInfo.name
+ "\" was indexed with docValuesType="
+ fieldInfo.getDocValuesType()
+ " but this type has docValuesType="
+ TYPE.docValuesType()
+ ", is the field really a LatLonDocValuesField?");
}
}
@Override
public String toString() {
StringBuilder result = new StringBuilder();
result.append(getClass().getSimpleName());
result.append(" <");
result.append(name);
result.append(':');
long currentValue = (Long) fieldsData;
result.append(decodeLatitude((int) (currentValue >> 32)));
result.append(',');
result.append(decodeLongitude((int) (currentValue & 0xFFFFFFFF)));
result.append('>');
return result.toString();
}
/**
* Creates a SortField for sorting by distance from a location.
*
*
This sort orders documents by ascending distance from the location. The value returned in
* {@link 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 {@link
* 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.
*
* @param field field name. must not be null.
* @param latitude latitude at the center: must be within standard +/-90 coordinate bounds.
* @param longitude longitude at the center: must be within standard +/-180 coordinate bounds.
* @return SortField ordering documents by distance
* @throws IllegalArgumentException if {@code field} is null or location has invalid coordinates.
*/
public static SortField newDistanceSort(String field, double latitude, double longitude) {
return new LatLonPointSortField(field, latitude, longitude);
}
/**
* 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 {@link IndexOrDocValuesQuery} alongside a
* {@link LatLonPoint#newBoxQuery}.
*/
public static Query newSlowBoxQuery(
String field,
double minLatitude,
double maxLatitude,
double minLongitude,
double maxLongitude) {
// exact double values of lat=90.0D and lon=180.0D must be treated special as they are not
// represented in the encoding
// and should not drag in extra bogus junk! TODO: should encodeCeil just throw
// ArithmeticException to be less trappy here?
if (minLatitude == 90.0) {
// range cannot match as 90.0 can never exist
return new MatchNoDocsQuery("LatLonDocValuesField.newBoxQuery with minLatitude=90.0");
}
if (minLongitude == 180.0) {
if (maxLongitude == 180.0) {
// range cannot match as 180.0 can never exist
return new MatchNoDocsQuery(
"LatLonDocValuesField.newBoxQuery with minLongitude=maxLongitude=180.0");
} else if (maxLongitude < minLongitude) {
// encodeCeil() with dateline wrapping!
minLongitude = -180.0;
}
}
return new LatLonDocValuesBoxQuery(field, minLatitude, maxLatitude, minLongitude, maxLongitude);
}
/**
* 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 {@link
* IndexOrDocValuesQuery} alongside a {@link LatLonPoint#newDistanceQuery}.
*
* @param field field name. must not be null.
* @param latitude latitude at the center: must be within standard +/-90 coordinate bounds.
* @param longitude longitude at the center: must be within standard +/-180 coordinate bounds.
* @param radiusMeters maximum distance from the center in meters: must be non-negative and
* finite.
* @return query matching points within this distance
* @throws IllegalArgumentException if {@code field} is null, location has invalid coordinates, or
* radius is invalid.
*/
public static Query newSlowDistanceQuery(
String field, double latitude, double longitude, double radiusMeters) {
Circle circle = new Circle(latitude, longitude, radiusMeters);
return newSlowGeometryQuery(field, ShapeField.QueryRelation.INTERSECTS, circle);
}
/**
* Create a query for matching points within the supplied polygons. 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 {@link IndexOrDocValuesQuery} alongside a
* {@link LatLonPoint#newPolygonQuery(String, Polygon...)}.
*
* @param field field name. must not be null.
* @param polygons array of polygons. must not be null or empty.
* @return query matching points within the given polygons.
* @throws IllegalArgumentException if {@code field} is null or polygons is empty or contain a
* null polygon.
*/
public static Query newSlowPolygonQuery(String field, Polygon... polygons) {
return newSlowGeometryQuery(field, ShapeField.QueryRelation.INTERSECTS, polygons);
}
/**
* Create a query for matching one or more geometries against the provided {@link
* ShapeField.QueryRelation}. Line geometries are not supported for WITHIN relationship. 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 {@link
* IndexOrDocValuesQuery} alongside a {@link LatLonPoint#newGeometryQuery(String,
* ShapeField.QueryRelation, LatLonGeometry...)}.
*
* @param field field name. must not be null.
* @param queryRelation The relation the points needs to satisfy with the provided geometries,
* must not be null.
* @param latLonGeometries array of LatLonGeometries. must not be null or empty.
* @return query matching points within the given polygons.
* @throws IllegalArgumentException if {@code field} is null, {@code queryRelation} is null,
* {@code latLonGeometries} is null, empty or contain a null or line geometry.
*/
public static Query newSlowGeometryQuery(
String field, ShapeField.QueryRelation queryRelation, LatLonGeometry... latLonGeometries) {
if (queryRelation == ShapeField.QueryRelation.INTERSECTS
&& latLonGeometries.length == 1
&& latLonGeometries[0] instanceof Rectangle) {
LatLonGeometry geometry = latLonGeometries[0];
Rectangle rect = (Rectangle) geometry;
return newSlowBoxQuery(field, rect.minLat, rect.maxLat, rect.minLon, rect.maxLon);
}
if (queryRelation == ShapeField.QueryRelation.CONTAINS) {
for (LatLonGeometry geometry : latLonGeometries) {
if ((geometry instanceof Point) == false) {
return new MatchNoDocsQuery(
"Contains LatLonDocValuesField.newSlowGeometryQuery with non-point geometries");
}
}
}
return new LatLonDocValuesQuery(field, queryRelation, latLonGeometries);
}
}