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

Package org.apache.lucene.index

# Class ByteVectorValues

java.lang.Object
org.apache.lucene.index.KnnVectorValues
org.apache.lucene.index.ByteVectorValues

Direct Known Subclasses:
  `BaseQuantizedByteVectorValues`, `OffHeapByteVectorValues`

public abstract class ByteVectorValues extends KnnVectorValues
This class provides access to per-document floating point vector values indexed as `KnnByteVectorField`.

WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.index.KnnVectorValues

  `KnnVectorValues.DocIndexIterator`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ByteVectorValues()`
  Sole constructor

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `checkField(LeafReader in, String field)`
  Checks the Vector Encoding of a field
  `abstract ByteVectorValues`
  `copy()`
  Creates a new copy of this `KnnVectorValues`.
  `static ByteVectorValues`
  `fromBytes(List<byte[]> vectors, int dim)`
  Creates a `ByteVectorValues` from a list of byte arrays.
  `VectorEncoding`
  `getEncoding()`
  The vector encoding of these values.
  `VectorScorer`
  `rescorer(byte[] target)`
  Rescore using the given query vector and the current `ByteVectorValues`.
  `VectorScorer`
  `scorer(byte[] query)`
  Return a `VectorScorer` for the given query vector.
  `abstract byte[]`
  `vectorValue(int ord)`
  Return the vector value for the given vector ordinal which must be in [0, size() - 1], otherwise IndexOutOfBoundsException is thrown.

  ### Methods inherited from class org.apache.lucene.index.KnnVectorValues

  `createDenseIterator, createSparseIterator, dimension, fromDISI, getAcceptOrds, getVectorByteLength, iterator, ordToDoc, prefetch, size`

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

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

- ## Constructor Details

  - ### ByteVectorValues

    protected ByteVectorValues()
    Sole constructor

- ## Method Details

  - ### vectorValue

    public abstract byte[] vectorValue(int ord) throws IOException
    Return the vector value for the given vector ordinal which must be in [0, size() - 1], otherwise IndexOutOfBoundsException is thrown. The returned array may be shared across calls.
    Returns:
      the vector value
    Throws:
      `IOException`

  - ### copy

    public abstract ByteVectorValues copy() throws IOException
    Description copied from class: `KnnVectorValues`
    Creates a new copy of this `KnnVectorValues`. This is helpful when you need to access different values at once, to avoid overwriting the underlying vector returned.
    Specified by:
      `copy` in class `KnnVectorValues`
    Throws:
      `IOException`

  - ### checkField

    public static void checkField(LeafReader in, String field)
    Checks the Vector Encoding of a field
    Throws:
      `IllegalStateException` - if `field` has vectors, but using a different encoding
    WARNING: This API is experimental and might change in incompatible ways in the next release.
    NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

  - ### scorer

    public VectorScorer scorer(byte[] query) throws IOException
    Return a `VectorScorer` for the given query vector. When the underlying format quantizes the vectors, this will return a `VectorScorer` that scores against the quantized vectors.
    Parameters:
      `query` - the query vector
    Returns:
      a `VectorScorer` instance or null
    Throws:
      `IOException`

  - ### rescorer

    public VectorScorer rescorer(byte[] target) throws IOException
    Rescore using the given query vector and the current `ByteVectorValues`. This is unique from scorer() in that it is explicitly for rescoring an existing set of hits and thus will often utilize the highest fidelity scoring algorithm available. This is useful when the initial search used a quantized index or an approximate scoring algorithm, and now we want to rescore the hits using the full fidelity vectors. The default implementation is to call `scorer(byte[])` assuming that the scorer is already the highest fidelity implementation available.
    Parameters:
      `target` - the query vector
    Returns:
      a `VectorScorer` instance or null
    Throws:
      `IOException` - if an I/O error occurs

  - ### getEncoding

    public VectorEncoding getEncoding()
    Description copied from class: `KnnVectorValues`
    The vector encoding of these values.
    Specified by:
      `getEncoding` in class `KnnVectorValues`

  - ### fromBytes

    public static ByteVectorValues fromBytes(List<byte[]> vectors, int dim)
    Creates a `ByteVectorValues` from a list of byte arrays.
    Parameters:
      `vectors` - the list of byte arrays
      `dim` - the dimension of the vectors
    Returns:
      a `ByteVectorValues` instancec