Package org.apache.lucene.index

Class BinaryDocValues

java.lang.Object
org.apache.lucene.search.DocIdSetIterator
org.apache.lucene.index.BinaryDocValues
Direct Known Subclasses:
BinaryRangeDocValues, FilterBinaryDocValues
public abstract class BinaryDocValues extends DocIdSetIterator
A per-document binary value.

  • Constructor Details

    • BinaryDocValues

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

  • Method Details

    • binaryValue

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

    • binaryValues

      public void binaryValues(int size, int[] docs, BytesRef[] values) throws IOException
      Bulk retrieval of binary 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 binaryValues(int size, int[] docs, BytesRef[] values) throws IOException {
   for (int i = 0; i < size; ++i) {
     int doc = docs[i];
     if (advanceExact(doc)) {
       values[i] = BytesRef.deepCopyOf(binaryValue());
     } else {
       values[i] = null;
     }
   }
 }

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

      NOTE: Documents that don't have a value for this field will have their corresponding entry set to null. If you need to exclude documents that don't have a value, then you could apply a FieldExistsQuery as a BooleanClause.Occur.FILTER clause. Another option is to fall back to using advanceExact(int) and binaryValue() on ranges of doc IDs that may not be dense, e.g. 

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

      NOTE: Each returned BytesRef is a deep copy owned by the caller and remains valid after subsequent calls.

      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; entries are set to null when a document doesn't have a value
      Throws:
      IOException

    • binaryValues

      public void binaryValues(int size, int[] docs, int docsOffset, BytesRef[] values, int valuesOffset) throws IOException
      Offset-aware variant of binaryValues(int, int[], BytesRef[]). 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; entries are set to null when a document doesn't have a value
      valuesOffset - first position in values to write
      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