org.apache.lucene.index

## Class PointValues

- java.lang.Object
- - org.apache.lucene.index.PointValues

- Direct Known Subclasses:
    BKDReader, MutablePointValues

      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

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

  * 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 and Description
    --- | ---
    `static interface` | `PointValues.IntersectVisitor` We recurse the BKD tree, using a provided instance of this to guide the recursion.
    `static class` | `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 and Description
    --- | ---
    `static int` | `MAX_DIMENSIONS` Maximum number of dimensions
    `static int` | `MAX_NUM_BYTES` Maximum number of bytes for each dimension

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `PointValues()` Default constructor

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract 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` | `getNumDataDimensions()` Returns how many data dimensions are represented in the values
    `abstract int` | `getNumIndexDimensions()` Returns how many dimensions are used for the index
    `abstract void` | `intersect(PointValues.IntersectVisitor visitor)` Finds all documents and points matching the provided visitor.
    `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 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

  - ### Constructor Detail

    - #### PointValues

          protected PointValues()

      Default constructor

  - ### Method Detail

    - #### 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()`

    - #### intersect

          public abstract 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 abstract 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)`.
      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`

    - #### getNumDataDimensions

          public abstract int getNumDataDimensions()
                                            throws IOException

      Returns how many data 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.

Copyright © 2000-2018 Apache Software Foundation. All Rights Reserved.