Package org.apache.lucene.index
Class PointValues
java.lang.Object
org.apache.lucene.index.PointValues
- Direct Known Subclasses:
BKDReader
Access to indexed numeric values.
* in the lucene-sandbox jar
Points represent numeric values and are indexed differently than ordinary text. Instead of an inverted index, points are indexed with datastructures such as KD-trees. These structures are optimized for operations such as range, distance, nearest-neighbor, and point-in-polygon queries.
Basic Point Types
| Java type | Lucene class |
|---|---|
int | IntPoint |
long | LongPoint |
float | FloatPoint |
double | DoublePoint |
byte[] | BinaryPoint |
InetAddress | InetAddressPoint |
BigInteger | BigIntegerPoint* |
Basic Lucene point types behave like their java peers: for example IntPoint represents
a signed 32-bit Integer, supporting values ranging from Integer.MIN_VALUE to
Integer.MAX_VALUE, ordered consistent with Integer.compareTo(Integer). In
addition to indexing support, point classes also contain static methods (such as IntPoint.newRangeQuery(String, int, int)) for creating common queries. For example:
// add year 1970 to document
document.add(new IntPoint("year", 1970));
// index document
writer.addDocument(document);
...
// issue range query of 1960-1980
Query query = IntPoint.newRangeQuery("year", 1960, 1980);
TopDocs docs = searcher.search(query, ...);
Geospatial Point Types
Although basic point types such asDoublePoint support points in multi-dimensional space
too, Lucene has specialized classes for location data. These classes are optimized for location
data: they are more space-efficient and support special operations such as distance and
polygon queries. There are currently two implementations: LatLonPoint: indexes(latitude,longitude)as(x,y)in two-dimensional space.- Geo3DPoint*
in lucene-spatial3d: indexes
(latitude,longitude)as(x,y,z)in three-dimensional space.
Advanced usage
Custom structures can be created on top of single- or multi- dimensional basic types, on top ofBinaryPoint for more flexibility, or via custom Field subclasses.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interfaceWe recurse thePointValues.PointTree, using a provided instance of this to guide the recursion.static interfaceBasic operations to read the KD-tree.static enumUsed byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)to check how each recursive cell corresponds to the query. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intMaximum number of dimensionsstatic final intMaximum number of index dimensionsstatic final intMaximum number of bytes for each dimension -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal longEstimate the number of documents that would be matched byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)with the givenPointValues.IntersectVisitor.final longEstimate the number of points that would be visited byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)with the givenPointValues.IntersectVisitor.abstract intReturns the number of bytes per dimensionabstract intReturns the total number of documents that have indexed at least one point.static intgetDocCount(IndexReader reader, String field) Return the cumulated number of docs that have points across all leaves of the givenIndexReader.abstract byte[]Returns maximum value for each dimension, packed, or null ifsize(org.apache.lucene.index.IndexReader, java.lang.String)is0static byte[]getMaxPackedValue(IndexReader reader, String field) Return the maximum packed values across all leaves of the givenIndexReader.abstract byte[]Returns minimum value for each dimension, packed, or null ifsize(org.apache.lucene.index.IndexReader, java.lang.String)is0static byte[]getMinPackedValue(IndexReader reader, String field) Return the minimum packed values across all leaves of the givenIndexReader.abstract intReturns how many dimensions are represented in the valuesabstract intReturns how many dimensions are used for the indexabstract PointValues.PointTreeCreate a newPointValues.PointTreeto navigate the indexfinal voidintersect(PointValues.IntersectVisitor visitor) Finds all documents and points matching the provided visitor.static booleanisEstimatedPointCountGreaterThanOrEqualTo(PointValues.IntersectVisitor visitor, PointValues.PointTree pointTree, long upperBound) Estimate if the point count that would be matched byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)with the givenPointValues.IntersectVisitoris greater than or equal to the upperBound.abstract longsize()Returns the total number of indexed points across all documents.static longsize(IndexReader reader, String field) Return the cumulated number of points across all leaves of the givenIndexReader.
-
Field Details
-
MAX_NUM_BYTES
public static final int MAX_NUM_BYTESMaximum number of bytes for each dimension- See Also:
-
MAX_DIMENSIONS
public static final int MAX_DIMENSIONSMaximum number of dimensions- See Also:
-
MAX_INDEX_DIMENSIONS
public static final int MAX_INDEX_DIMENSIONSMaximum number of index dimensions- See Also:
-
-
Constructor Details
-
PointValues
protected PointValues()Default constructor
-
-
Method Details
-
size
Return the cumulated number of points across all leaves of the givenIndexReader. Leaves that do not have points for the given field are ignored.- Throws:
IOException- See Also:
-
getDocCount
Return the cumulated number of docs that have points across all leaves of the givenIndexReader. Leaves that do not have points for the given field are ignored.- Throws:
IOException- See Also:
-
getMinPackedValue
Return the minimum packed values across all leaves of the givenIndexReader. Leaves that do not have points for the given field are ignored.- Throws:
IOException- See Also:
-
getMaxPackedValue
Return the maximum packed values across all leaves of the givenIndexReader. Leaves that do not have points for the given field are ignored.- Throws:
IOException- See Also:
-
getPointTree
Create a newPointValues.PointTreeto navigate the index- Throws:
IOException
-
intersect
Finds all documents and points matching the provided visitor. This method does not enforce live documents, so it's up to the caller to test whether each document is deleted, if necessary.- Throws:
IOException
-
estimatePointCount
Estimate the number of points that would be visited byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)with the givenPointValues.IntersectVisitor. This should run many times faster thanintersect(IntersectVisitor). -
isEstimatedPointCountGreaterThanOrEqualTo
public static boolean isEstimatedPointCountGreaterThanOrEqualTo(PointValues.IntersectVisitor visitor, PointValues.PointTree pointTree, long upperBound) throws IOException Estimate if the point count that would be matched byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)with the givenPointValues.IntersectVisitoris greater than or equal to the upperBound.- Throws:
IOException- NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.
-
estimateDocCount
Estimate the number of documents that would be matched byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)with the givenPointValues.IntersectVisitor. This should run many times faster thanintersect(IntersectVisitor).- See Also:
-
getMinPackedValue
Returns minimum value for each dimension, packed, or null ifsize(org.apache.lucene.index.IndexReader, java.lang.String)is0- Throws:
IOException
-
getMaxPackedValue
Returns maximum value for each dimension, packed, or null ifsize(org.apache.lucene.index.IndexReader, java.lang.String)is0- Throws:
IOException
-
getNumDimensions
Returns how many dimensions are represented in the values- Throws:
IOException
-
getNumIndexDimensions
Returns how many dimensions are used for the index- Throws:
IOException
-
getBytesPerDimension
Returns the number of bytes per dimension- Throws:
IOException
-
size
public abstract long size()Returns the total number of indexed points across all documents. -
getDocCount
public abstract int getDocCount()Returns the total number of documents that have indexed at least one point.
-