Class PointValues

  • Direct Known Subclasses:
    BKDReader, ExitableDirectoryReader.ExitablePointValues, MemoryIndex.MemoryIndexReader.MemoryIndexPointValues, MutablePointValues, SimpleTextBKDReader, SortingLeafReader.SortingPointValues

    public abstract class PointValues
    extends java.lang.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

    Java typeLucene class
    intIntPoint
    longLongPoint
    floatFloatPoint
    doubleDoublePoint
    byte[]BinaryPoint
    BigIntegerBigIntegerPoint*
    InetAddressInetAddressPoint*
    * in the lucene-sandbox jar

    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 as DoublePoint 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:
    1. LatLonPoint: indexes (latitude,longitude) as (x,y) in two-dimensional space.
    2. Geo3DPoint* in lucene-spatial3d: indexes (latitude,longitude) as (x,y,z) in three-dimensional space.
    * does not support altitude, 3D here means "uses three dimensions under-the-hood"

    Advanced usage

    Custom structures can be created on top of single- or multi- dimensional basic types, on top of BinaryPoint for more flexibility, or via custom Field subclasses.
    • 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
    • Constructor Detail

      • PointValues

        protected PointValues()
        Default constructor
    • Method Detail

      • size

        public static long size​(IndexReader reader,
                                java.lang.String field)
                         throws java.io.IOException
        Return the cumulated number of points across all leaves of the given IndexReader. Leaves that do not have points for the given field are ignored.
        Throws:
        java.io.IOException
        See Also:
        size()
      • getDocCount

        public static int getDocCount​(IndexReader reader,
                                      java.lang.String field)
                               throws java.io.IOException
        Return the cumulated number of docs that have points across all leaves of the given IndexReader. Leaves that do not have points for the given field are ignored.
        Throws:
        java.io.IOException
        See Also:
        getDocCount()
      • getMinPackedValue

        public static byte[] getMinPackedValue​(IndexReader reader,
                                               java.lang.String field)
                                        throws java.io.IOException
        Return the minimum packed values across all leaves of the given IndexReader. Leaves that do not have points for the given field are ignored.
        Throws:
        java.io.IOException
        See Also:
        getMinPackedValue()
      • getMaxPackedValue

        public static byte[] getMaxPackedValue​(IndexReader reader,
                                               java.lang.String field)
                                        throws java.io.IOException
        Return the maximum packed values across all leaves of the given IndexReader. Leaves that do not have points for the given field are ignored.
        Throws:
        java.io.IOException
        See Also:
        getMaxPackedValue()
      • intersect

        public abstract void intersect​(PointValues.IntersectVisitor visitor)
                                throws java.io.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:
        java.io.IOException
      • getNumDimensions

        public abstract int getNumDimensions()
                                      throws java.io.IOException
        Returns how many dimensions are represented in the values
        Throws:
        java.io.IOException
      • getNumIndexDimensions

        public abstract int getNumIndexDimensions()
                                           throws java.io.IOException
        Returns how many dimensions are used for the index
        Throws:
        java.io.IOException
      • getBytesPerDimension

        public abstract int getBytesPerDimension()
                                          throws java.io.IOException
        Returns the number of bytes per dimension
        Throws:
        java.io.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.