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.

  • 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