Package org.apache.lucene.codecs.hnsw

Class FlatVectorsWriter

java.lang.Object

org.apache.lucene.codecs.KnnVectorsWriter

org.apache.lucene.codecs.hnsw.FlatVectorsWriter

All Implemented Interfaces:

Closeable, AutoCloseable, Accountable

Direct Known Subclasses:

Lucene104ScalarQuantizedVectorsWriter, Lucene99FlatVectorsWriter

public abstract class FlatVectorsWriter
extends KnnVectorsWriter

Vectors' writer for a field that allows additional indexing logic to be implemented by the caller

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	FlatVectorsWriter.MergeScorerData	Data prepared while merging a field for scoring its merged vectors.

Nested classes/interfaces inherited from class org.apache.lucene.codecs.KnnVectorsWriter

KnnVectorsWriter.MergedVectorValues

Field Summary

Fields

Modifier and Type	Field	Description
protected final FlatVectorsScorer	vectorsScorer	Scorer for flat vectors

Fields inherited from interface org.apache.lucene.util.Accountable

NULL_ACCOUNTABLE

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	FlatVectorsWriter(FlatVectorsScorer vectorsScorer)	Sole constructor

Method Summary

Modifier and Type	Method	Description
abstract FlatFieldVectorsWriter<?>	addField(FieldInfo fieldInfo)	Add a new field for indexing
FlatVectorsScorer	getFlatVectorScorer()
final IORunnable	mergeOneField(FieldInfo fieldInfo, MergeState mergeState)	Merges vectors for a single field, returning a runnable for any deferred work (e.g., HNSW graph construction).
abstract void	mergeOneFlatVectorField(FieldInfo fieldInfo, MergeState mergeState)
FlatVectorsWriter.MergeScorerData	mergeOneFlatVectorFieldForMergeScorer(FieldInfo fieldInfo, MergeState mergeState, IntPredicate needsMergeScorer)	Merges one field and, while writing the merged vectors, optionally prepares what a merge scorer needs, so that the merged float vectors need not be read back.

Methods inherited from class org.apache.lucene.codecs.KnnVectorsWriter

finish, flush, mapOldOrdToNewOrd, merge

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.lucene.util.Accountable

getChildResources, ramBytesUsed

Methods inherited from interface java.io.Closeable

close

Field Details

vectorsScorer

protected final FlatVectorsScorer vectorsScorer

Scorer for flat vectors

Constructor Details

FlatVectorsWriter

protected FlatVectorsWriter(FlatVectorsScorer vectorsScorer)

Sole constructor

Method Details

getFlatVectorScorer

public FlatVectorsScorer getFlatVectorScorer()

Returns:

the FlatVectorsScorer for this reader.

addField

public abstract FlatFieldVectorsWriter<?> addField(FieldInfo fieldInfo)
                                            throws IOException

Add a new field for indexing

Specified by:

addField in class KnnVectorsWriter

Parameters:

fieldInfo - fieldInfo of the field to add

Returns:

a writer for the field

Throws:

IOException - if an I/O error occurs when adding the field

mergeOneField

public final IORunnable mergeOneField(FieldInfo fieldInfo,
 MergeState mergeState)
                               throws IOException

Description copied from class: KnnVectorsWriter

Merges vectors for a single field, returning a runnable for any deferred work (e.g., HNSW graph construction). The default implementation merges naively the vectors and returns null (no deferred work).

Subclasses should override this method may implement a two-phase merge strategy where flat vectors are written in the first phase and additional indexing structures (like HNSW graphs) are built in the second phase using the already-written flat vector data.

Overrides:

mergeOneField in class KnnVectorsWriter

Parameters:

fieldInfo - the field to merge

mergeState - the merge state

Returns:

a runnable to execute in phase 2, or null if there is no deferred work

Throws:

IOException - if an I/O error occurs

mergeOneFlatVectorField

public abstract void mergeOneFlatVectorField(FieldInfo fieldInfo,
 MergeState mergeState)
                                      throws IOException

Throws:

IOException

mergeOneFlatVectorFieldForMergeScorer

public FlatVectorsWriter.MergeScorerData mergeOneFlatVectorFieldForMergeScorer(FieldInfo fieldInfo,
 MergeState mergeState,
 IntPredicate needsMergeScorer)
                                                                        throws IOException

Merges one field and, while writing the merged vectors, optionally prepares what a merge scorer needs, so that the merged float vectors need not be read back.

A wrapping writer should forward this method along with mergeOneFlatVectorField(org.apache.lucene.index.FieldInfo, org.apache.lucene.index.MergeState). Forwarding only the latter stays correct, but the wrapped writer then prepares nothing. Forwarding helps only when the wrapping format's reader over the merged segment is the wrapped writer's own reader. Otherwise FlatVectorsWriter.MergeScorerData.scorerSupplier(org.apache.lucene.codecs.hnsw.FlatVectorsReader) rejects the prepared data and the merge uses its fallback.

Parameters:

fieldInfo - field to merge

mergeState - merge state

needsMergeScorer - whether to prepare scorer data for a vector count. The writer applies this predicate to the number of live vectors written after deletions, so it does not prepare data for a merged field that is too small to build a graph.

Returns:

prepared data that the caller must close, or null if none was prepared, which is what the default implementation returns and what any writer returns for a field it cannot prepare for. The caller then builds the scorer itself.

Throws:

IOException - if an I/O error occurs