Apache/lucene
1
0
Fork 0
mirror of https://github.com/apache/lucene.git synced 2025-02-15 06:25:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

improve javadocs for LatLonPoint.nearest()

Browse Source
This commit is contained in:
Robert Muir 2016-04-15 14:45:22 -04:00
parent 8f2a3a5271
commit 40e3e1e72e
1 changed files with 21 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java
View File

@ -64,6 +64,7 @@ import static org.apache.lucene.geo.GeoEncodingUtils.encodeLongitudeCeil;
* <li>{@link #newDistanceQuery newDistanceQuery()} for matching points within a specified distance. * <li>{@link #newDistanceQuery newDistanceQuery()} for matching points within a specified distance.
* <li>{@link #newDistanceSort newDistanceSort()} for ordering documents by distance from a specified location. * <li>{@link #newDistanceSort newDistanceSort()} for ordering documents by distance from a specified location.
* <li>{@link #newPolygonQuery newPolygonQuery()} for matching points within an arbitrary polygon. * <li>{@link #newPolygonQuery newPolygonQuery()} for matching points within an arbitrary polygon.
* <li>{@link #nearest nearest()} for finding the k-nearest neighbors by distance.
* </ul> * </ul>
* <p> * <p>
* <b>WARNING</b>: Values are indexed with some loss of precision from the * <b>WARNING</b>: Values are indexed with some loss of precision from the
@ -304,24 +305,39 @@ public class LatLonPoint extends Field {
} }
/** /**
* Finds the {@code topN} nearest indexed points to the provided point, according to Haversine distance. * Finds the {@code n} nearest indexed points to the provided point, according to Haversine distance.
* <p>
* This is functionally equivalent to running {@link MatchAllDocsQuery} with a {@link #newDistanceSort}, * This is functionally equivalent to running {@link MatchAllDocsQuery} with a {@link #newDistanceSort},
* but is far more efficient since it takes advantage of properties the indexed BKD tree. Currently this * but is far more efficient since it takes advantage of properties the indexed BKD tree. Currently this
* only works with {@link Lucene60PointsFormat} (used by the default codec). * only works with {@link Lucene60PointsFormat} (used by the default codec).
* <p>
* Documents are ordered by ascending distance from the location. The value returned in {@link FieldDoc} for
* the hits contains a Double instance with the distance in meters.
*
* @param searcher IndexSearcher to find nearest points from.
* @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 n the number of nearest neighbors to retrieve.
* @return TopFieldDocs containing documents ordered by distance.
* @throws IllegalArgumentException if the underlying PointValues is not a {@code Lucene60PointsReader} (this is a current limitation).
* @throws IOException if an IOException occurs while finding the points.
*/ */
public static TopFieldDocs nearest(IndexSearcher s, String fieldName, double latitude, double longitude, int n) throws IOException { // TODO: what about multi-valued documents? what happens?
// TODO: parameter checking, what if i pass a negative n, bogus latitude, null field,etc?
public static TopFieldDocs nearest(IndexSearcher searcher, String field, double latitude, double longitude, int n) throws IOException {
List<BKDReader> readers = new ArrayList<>(); List<BKDReader> readers = new ArrayList<>();
List<Integer> docBases = new ArrayList<>(); List<Integer> docBases = new ArrayList<>();
List<Bits> liveDocs = new ArrayList<>(); List<Bits> liveDocs = new ArrayList<>();
int totalHits = 0; int totalHits = 0;
for(LeafReaderContext leaf : s.getIndexReader().leaves()) { for(LeafReaderContext leaf : searcher.getIndexReader().leaves()) {
PointValues points = leaf.reader().getPointValues(); PointValues points = leaf.reader().getPointValues();
if (points != null) { if (points != null) {
if (points instanceof Lucene60PointsReader == false) { if (points instanceof Lucene60PointsReader == false) {
throw new IllegalArgumentException("can only run on Lucene60PointsReader points implementation, but got " + points); throw new IllegalArgumentException("can only run on Lucene60PointsReader points implementation, but got " + points);
} }
totalHits += points.getDocCount(fieldName); totalHits += points.getDocCount(field);
BKDReader reader = ((Lucene60PointsReader) points).getBKDReader(fieldName); BKDReader reader = ((Lucene60PointsReader) points).getBKDReader(field);
if (reader != null) { if (reader != null) {
readers.add(reader); readers.add(reader);
docBases.add(leaf.docBase); docBases.add(leaf.docBase);