NumericDocValues (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.index, class: NumericDocValues

Package org.apache.lucene.index

# Class NumericDocValues

java.lang.Object
org.apache.lucene.search.DocIdSetIterator
org.apache.lucene.index.NumericDocValues

Direct Known Subclasses:
  `FilterNumericDocValues`

public abstract class NumericDocValues extends DocIdSetIterator
A per-document numeric value.

- ## Field Summary

  ### Fields inherited from class org.apache.lucene.search.DocIdSetIterator

  `NO_MORE_DOCS`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `NumericDocValues()`
  Sole constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract boolean`
  `advanceExact(int target)`
  Advance the iterator to exactly `target` and return whether `target` has a value.
  `abstract long`
  `longValue()`
  Returns the numeric value for the current document ID.
  `void`
  `longValues(int size, int[] docs, int docsOffset, long[] values, int valuesOffset, long defaultValue)`
  Offset-aware variant of `longValues(int, int[], long[], long)`.
  `void`
  `longValues(int size, int[] docs, long[] values, long defaultValue)`
  Bulk retrieval of numeric doc values.
  `void`
  `rangeIntoBitSet(int fromDoc, int toDoc, long minValue, long maxValue, FixedBitSet bitSet, int offset)`
  Fills a `FixedBitSet` with the doc IDs in `[fromDoc, toDoc)` whose values are in `[minValue, maxValue]`.

  ### Methods inherited from class org.apache.lucene.search.DocIdSetIterator

  `advance, all, cost, docID, docIDRunEnd, empty, intoBitSet, nextDoc, range, slowAdvance`

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

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

- ## Constructor Details

  - ### NumericDocValues

    protected NumericDocValues()
    Sole constructor. (For invocation by subclass constructors, typically implicit.)

- ## Method Details

  - ### longValue

    public abstract long longValue() throws IOException
    Returns the numeric value for the current document ID. It is illegal to call this method after `advanceExact(int)` returned `false`.
    Returns:
      numeric value
    Throws:
      `IOException`

  - ### longValues

    public void longValues(int size, int[] docs, long[] values, long defaultValue) throws IOException
    Bulk retrieval of numeric doc values. This API helps reduce the performance impact of virtual function calls.

    This API behaves as if implemented as below, which is the default implementation:

         public void longValues(int size, int[] docs, long[] values, long defaultValue) throws IOException {
           for (int i = 0; i < size; ++i) {
             int doc = docs[i];
             long value;
             if (advanceExact(doc)) {
               value = longValue();
             } else {
               value = defaultValue;
             }
             values[i] = value;
           }
         }

    NOTE: The `docs` array is required to be sorted in ascending order with no duplicates.

    NOTE: This API doesn't allow callers to know which doc IDs have a value or not. If you need to exclude documents that don't have a value for this field, then you could apply a `FieldExistsQuery` as a `BooleanClause.Occur.FILTER` clause. Another option is to fall back to using `advanceExact(int)` and `longValue()` on ranges of doc IDs that may not be dense, e.g.

         if (size > 0 && values.advannceExact(docs[0]) && values.docIDRunEnd() > docs[size - 1]) {
           // use values#longValues to retrieve values
         } else {
           // some docs may not have a value, use #advanceExact and #longValue
         }

    Parameters:
      `size` - the number of values to retrieve
      `docs` - the buffer of doc IDs whose values should be looked up
      `values` - the buffer of values to fill
      `defaultValue` - the value to put in the buffer when a document doesn't have a value
    Throws:
      `IOException`

  - ### longValues

    public void longValues(int size, int[] docs, int docsOffset, long[] values, int valuesOffset, long defaultValue) throws IOException
    Offset-aware variant of `longValues(int, int[], long[], long)`. Reads `size` doc IDs starting at `docs[docsOffset]` and writes the corresponding values starting at `values[valuesOffset]`. This follows the same convention as `System.arraycopy(java.lang.Object, int, java.lang.Object, int, int)`.
    Parameters:
      `size` - the number of values to retrieve
      `docs` - the buffer of doc IDs whose values should be looked up
      `docsOffset` - first position in `docs` to read
      `values` - the buffer of values to fill
      `valuesOffset` - first position in `values` to write
      `defaultValue` - the value to put in the buffer when a document doesn't have a value
    Throws:
      `IOException`

  - ### rangeIntoBitSet

    public void rangeIntoBitSet(int fromDoc, int toDoc, long minValue, long maxValue, FixedBitSet bitSet, int offset) throws IOException
    Fills a `FixedBitSet` with the doc IDs in `[fromDoc, toDoc)` whose values are in `[minValue, maxValue]`. This is a bulk operation that avoids per-doc virtual dispatch overhead.

    The default implementation falls back to per-doc evaluation via `advanceExact(int)` and `longValue()`. Subclasses with random-access storage (e.g., dense fixed-bitsPerValue fields) can override this for significantly better performance.

    Parameters:
      `fromDoc` - first doc ID to evaluate (inclusive)
      `toDoc` - last doc ID to evaluate (exclusive)
      `minValue` - lower bound of the range (inclusive)
      `maxValue` - upper bound of the range (inclusive)
      `bitSet` - the bitset to fill
      `offset` - subtracted from each doc ID before setting the bit
    Throws:
      `IOException`

  - ### advanceExact

    public abstract boolean advanceExact(int target) throws IOException
    Advance the iterator to exactly `target` and return whether `target` has a value. `target` must be greater than or equal to the current `doc ID` and must be a valid doc ID, ie. ≥ 0 and < `maxDoc`. After this method returns, `DocIdSetIterator.docID()` returns `target`.

    Note: it is illegal to call `DocIdSetIterator.intoBitSet(int, org.apache.lucene.util.FixedBitSet, int)` or `DocIdSetIterator.docIDRunEnd()` when this method returns false.

    Throws:
      `IOException`