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

Basic point types in Java and Lucene
Java type | Lucene class
--- | ---
`int` | `IntPoint`
`long` | `LongPoint`
`float` | `FloatPoint`
`double` | `DoublePoint`
`byte[]` | `BinaryPoint`
`InetAddress` | `InetAddressPoint`
`BigInteger` | BigIntegerPoint*

* 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.

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 interface`
  `PointValues.IntersectVisitor`
  We recurse the `PointValues.PointTree`, using a provided instance of this to guide the recursion.
  `static interface`
  `PointValues.PointTree`
  Basic operations to read the KD-tree.
  `static enum`
  `PointValues.Relation`
  Used by `intersect(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 final int`
  `MAX_DIMENSIONS`
  Maximum number of dimensions
  `static final int`
  `MAX_INDEX_DIMENSIONS`
  Maximum number of index dimensions
  `static final int`
  `MAX_NUM_BYTES`
  Maximum number of bytes for each dimension

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `PointValues()`
  Default constructor

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final long`
  `estimateDocCount(PointValues.IntersectVisitor visitor)`
  Estimate the number of documents that would be matched by `intersect(org.apache.lucene.index.PointValues.IntersectVisitor)` with the given `PointValues.IntersectVisitor`.
  `final long`
  `estimatePointCount(PointValues.IntersectVisitor visitor)`
  Estimate the number of points that would be visited by `intersect(org.apache.lucene.index.PointValues.IntersectVisitor)` with the given `PointValues.IntersectVisitor`.
  `abstract int`
  `getBytesPerDimension()`
  Returns the number of bytes per dimension
  `abstract int`
  `getDocCount()`
  Returns the total number of documents that have indexed at least one point.
  `static int`
  `getDocCount(IndexReader reader, String field)`
  Return the cumulated number of docs that have points across all leaves of the given `IndexReader`.
  `abstract byte[]`
  `getMaxPackedValue()`
  Returns maximum value for each dimension, packed, or null if `size(org.apache.lucene.index.IndexReader, java.lang.String)` is `0`
  `static byte[]`
  `getMaxPackedValue(IndexReader reader, String field)`
  Return the maximum packed values across all leaves of the given `IndexReader`.
  `abstract byte[]`
  `getMinPackedValue()`
  Returns minimum value for each dimension, packed, or null if `size(org.apache.lucene.index.IndexReader, java.lang.String)` is `0`
  `static byte[]`
  `getMinPackedValue(IndexReader reader, String field)`
  Return the minimum packed values across all leaves of the given `IndexReader`.
  `abstract int`
  `getNumDimensions()`
  Returns how many dimensions are represented in the values
  `abstract int`
  `getNumIndexDimensions()`
  Returns how many dimensions are used for the index
  `abstract PointValues.PointTree`
  `getPointTree()`
  Create a new `PointValues.PointTree` to navigate the index
  `final void`
  `intersect(PointValues.IntersectVisitor visitor)`
  Finds all documents and points matching the provided visitor.
  `static boolean`
  `isEstimatedPointCountGreaterThanOrEqualTo(PointValues.IntersectVisitor visitor, PointValues.PointTree pointTree, long upperBound)`
  Estimate if the point count that would be matched by `intersect(org.apache.lucene.index.PointValues.IntersectVisitor)` with the given `PointValues.IntersectVisitor` is greater than or equal to the upperBound.
  `abstract long`
  `size()`
  Returns the total number of indexed points across all documents.
  `static long`
  `size(IndexReader reader, String field)`
  Return the cumulated number of points across all leaves of the given `IndexReader`.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### 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 Details

  - ### PointValues

    protected PointValues()
    Default constructor

- ## Method Details

  - ### size

    public static long size(IndexReader reader, String field) throws 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:
      `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 given `IndexReader`. 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 given `IndexReader`. 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 given `IndexReader`. 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 new `PointValues.PointTree` to 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 by `intersect(org.apache.lucene.index.PointValues.IntersectVisitor)` with the given `PointValues.IntersectVisitor`. This should run many times faster than `intersect(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 by `intersect(org.apache.lucene.index.PointValues.IntersectVisitor)` with the given `PointValues.IntersectVisitor` is 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 by `intersect(org.apache.lucene.index.PointValues.IntersectVisitor)` with the given `PointValues.IntersectVisitor`. This should run many times faster than `intersect(IntersectVisitor)`.
    See Also:
      - `DocIdSetIterator.cost()`

  - ### getMinPackedValue

    public abstract byte[] getMinPackedValue() throws IOException
    Returns minimum value for each dimension, packed, or null if `size(org.apache.lucene.index.IndexReader, java.lang.String)` is `0`
    Throws:
      `IOException`

  - ### getMaxPackedValue

    public abstract byte[] getMaxPackedValue() throws IOException
    Returns maximum value for each dimension, packed, or null if `size(org.apache.lucene.index.IndexReader, java.lang.String)` is `0`
    Throws:
      `IOException`

  - ### getNumDimensions

    public abstract int getNumDimensions() throws IOException
    Returns how many dimensions are represented in the values
    Throws:
      `IOException`

  - ### getNumIndexDimensions

    public abstract int getNumIndexDimensions() throws IOException
    Returns how many dimensions are used for the index
    Throws:
      `IOException`

  - ### getBytesPerDimension

    public abstract int getBytesPerDimension() throws IOException
    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.