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.