Package org.apache.lucene.index
Class PointValues
- java.lang.Object
-
- org.apache.lucene.index.PointValues
-
- Direct Known Subclasses:
BKDReader
public abstract class PointValues extends Object
Access to indexed numeric values.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
* in the lucene-sandbox jarBasic point types in Java and Lucene Java type Lucene class intIntPointlongLongPointfloatFloatPointdoubleDoublePointbyte[]BinaryPointInetAddressInetAddressPointBigIntegerBigIntegerPoint*
Basic Lucene point types behave like their java peers: for example
IntPointrepresents a signed 32-bitInteger, supporting values ranging fromInteger.MIN_VALUEtoInteger.MAX_VALUE, ordered consistent withInteger.compareTo(Integer). In addition to indexing support, point classes also contain static methods (such asIntPoint.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 asDoublePointsupport 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 ofBinaryPointfor more flexibility, or via customFieldsubclasses.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interfacePointValues.IntersectVisitorWe recurse thePointValues.PointTree, using a provided instance of this to guide the recursion.static interfacePointValues.PointTreeBasic operations to read the KD-tree.static classPointValues.RelationUsed byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)to check how each recursive cell corresponds to the query.
-
Field Summary
Fields Modifier and Type Field Description static intMAX_DIMENSIONSMaximum number of dimensionsstatic intMAX_INDEX_DIMENSIONSMaximum number of index dimensionsstatic intMAX_NUM_BYTESMaximum number of bytes for each dimension
-
Constructor Summary
Constructors Modifier Constructor Description protectedPointValues()Default constructor
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description longestimateDocCount(PointValues.IntersectVisitor visitor)Estimate the number of documents that would be matched byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)with the givenPointValues.IntersectVisitor.longestimatePointCount(PointValues.IntersectVisitor visitor)Estimate the number of points that would be visited byintersect(org.apache.lucene.index.PointValues.IntersectVisitor)with the givenPointValues.IntersectVisitor.abstract intgetBytesPerDimension()Returns the number of bytes per dimensionabstract intgetDocCount()Returns 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[]getMaxPackedValue()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[]getMinPackedValue()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 intgetNumDimensions()Returns how many dimensions are represented in the valuesabstract intgetNumIndexDimensions()Returns how many dimensions are used for the indexabstract PointValues.PointTreegetPointTree()Create a newPointValues.PointTreeto navigate the indexvoidintersect(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 Detail
-
MAX_NUM_BYTES
public static final int MAX_NUM_BYTES
Maximum number of bytes for each dimension- See Also:
- Constant Field Values
-
MAX_DIMENSIONS
public static final int MAX_DIMENSIONS
Maximum number of dimensions- See Also:
- Constant Field Values
-
MAX_INDEX_DIMENSIONS
public static final int MAX_INDEX_DIMENSIONS
Maximum number of index dimensions- See Also:
- Constant Field Values
-
-
Method Detail
-
size
public static long size(IndexReader reader, String field) throws IOException
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:
size()
-
getDocCount
public static int getDocCount(IndexReader reader, String field) throws IOException
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:
getDocCount()
-
getMinPackedValue
public static byte[] getMinPackedValue(IndexReader reader, String field) throws IOException
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:
getMinPackedValue()
-
getMaxPackedValue
public static byte[] getMaxPackedValue(IndexReader reader, String field) throws IOException
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:
getMaxPackedValue()
-
getPointTree
public abstract PointValues.PointTree getPointTree() throws IOException
Create a newPointValues.PointTreeto navigate the index- Throws:
IOException
-
intersect
public final void intersect(PointValues.IntersectVisitor visitor) throws IOException
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
public final long estimatePointCount(PointValues.IntersectVisitor visitor)
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
public final long estimateDocCount(PointValues.IntersectVisitor visitor)
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:
DocIdSetIterator.cost()
-
getMinPackedValue
public abstract byte[] getMinPackedValue() throws IOExceptionReturns minimum value for each dimension, packed, or null ifsize(org.apache.lucene.index.IndexReader, java.lang.String)is0- Throws:
IOException
-
getMaxPackedValue
public abstract byte[] getMaxPackedValue() throws IOExceptionReturns maximum value for each dimension, packed, or null ifsize(org.apache.lucene.index.IndexReader, java.lang.String)is0- Throws:
IOException
-
getNumDimensions
public abstract int getNumDimensions() throws IOExceptionReturns how many dimensions are represented in the values- Throws:
IOException
-
getNumIndexDimensions
public abstract int getNumIndexDimensions() throws IOExceptionReturns how many dimensions are used for the index- Throws:
IOException
-
getBytesPerDimension
public abstract int getBytesPerDimension() throws IOExceptionReturns 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.
-
-