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, tokenStream, 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 Detail

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 Detail

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