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

Package org.apache.lucene.document

# Class KnnByteVectorField

java.lang.Object
org.apache.lucene.document.Field
org.apache.lucene.document.KnnByteVectorField

All Implemented Interfaces:
  `IndexableField`

public class KnnByteVectorField extends Field
A field that contains a single byte numeric vector (or none) for each document. Vectors are dense - that is, every dimension of a vector contains an explicit value, stored packed into an array (of type byte[]) whose length is the vector dimension. Values can be retrieved using `ByteVectorValues`, which is a forward-only docID-based iterator and also offers random-access by dense ordinal (not docId). `VectorSimilarityFunction` may be used to compare vectors at query time (for example as part of result ranking). A KnnByteVectorField may be associated with a search similarity function defining the metric used for nearest-neighbor search among vectors of that field.

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.document.Field

  `Field.Store`

- ## Field Summary

  ### Fields inherited from class org.apache.lucene.document.Field

  `fieldsData, name, type`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `KnnByteVectorField(String name, byte[] vector)`
  Creates a numeric vector field with the default EUCLIDEAN_HNSW (L2) similarity.
  `KnnByteVectorField(String name, byte[] vector, FieldType fieldType)`
  Creates a numeric vector field.
  `KnnByteVectorField(String name, byte[] vector, VectorSimilarityFunction similarityFunction)`
  Creates a numeric vector field.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static FieldType`
  `createFieldType(int dimension, VectorSimilarityFunction similarityFunction)`
  A convenience method for creating a vector field type.
  `static Query`
  `newVectorQuery(String field, byte[] queryVector, int k)`
  Create a new vector query for the provided field targeting the byte vector
  `void`
  `setVectorValue(byte[] value)`
  Set the vector value of this field
  `byte[]`
  `vectorValue()`
  Return the vector value of this field

  ### Methods inherited from class org.apache.lucene.document.Field

  `binaryValue, fieldType, getCharSequenceValue, invertableType, name, numericValue, readerValue, setBytesValue, setBytesValue, setByteValue, setDoubleValue, setFloatValue, setIntValue, setLongValue, setReaderValue, setShortValue, setStringValue, setTokenStream, storedValue, stringValue, tokenStream, tokenStreamValue, toString`

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

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

- ## Constructor Details

  - ### KnnByteVectorField

    public KnnByteVectorField(String name, byte[] vector, VectorSimilarityFunction similarityFunction)
    Creates a numeric vector field. Fields are single-valued: each document has either one value or no value. Vectors of a single field share the same dimension and similarity function. Note that some vector similarities (like `VectorSimilarityFunction.DOT_PRODUCT`) require values to be constant-length.
    Parameters:
      `name` - field name
      `vector` - value
      `similarityFunction` - a function defining vector proximity.
    Throws:
      `IllegalArgumentException` - if any parameter is null, or the vector is empty or has dimension > 1024.

  - ### KnnByteVectorField

    public KnnByteVectorField(String name, byte[] vector)
    Creates a numeric vector field with the default EUCLIDEAN_HNSW (L2) similarity. Fields are single-valued: each document has either one value or no value. Vectors of a single field share the same dimension and similarity function.
    Parameters:
      `name` - field name
      `vector` - value
    Throws:
      `IllegalArgumentException` - if any parameter is null, or the vector is empty or has dimension > 1024.

  - ### KnnByteVectorField

    public KnnByteVectorField(String name, byte[] vector, FieldType fieldType)
    Creates a numeric vector field. Fields are single-valued: each document has either one value or no value. Vectors of a single field share the same dimension and similarity function.
    Parameters:
      `name` - field name
      `vector` - value
      `fieldType` - field type
    Throws:
      `IllegalArgumentException` - if any parameter is null, or the vector is empty or has dimension > 1024.

- ## Method Details

  - ### newVectorQuery

    public static Query newVectorQuery(String field, byte[] queryVector, int k)
    Create a new vector query for the provided field targeting the byte vector
    Parameters:
      `field` - The field to query
      `queryVector` - The byte vector target
      `k` - The number of nearest neighbors to gather
    Returns:
      A new vector query

  - ### createFieldType

    public static FieldType createFieldType(int dimension, VectorSimilarityFunction similarityFunction)
    A convenience method for creating a vector field type.
    Parameters:
      `dimension` - dimension of vectors
      `similarityFunction` - a function defining vector proximity.
    Throws:
      `IllegalArgumentException` - if any parameter is null, or has dimension > 1024.

  - ### vectorValue

    public byte[] vectorValue()
    Return the vector value of this field

  - ### setVectorValue

    public void setVectorValue(byte[] value)
    Set the vector value of this field
    Parameters:
      `value` - the value to set; must not be null, and length must match the field type