Lucene92HnswVectorsFormat (Lucene 10.5.0 backward-codecs API)
Description: declaration: package: org.apache.lucene.backward_codecs.lucene92, class: Lucene92HnswVectorsFormat

Package org.apache.lucene.backward_codecs.lucene92

# Class Lucene92HnswVectorsFormat

java.lang.Object
org.apache.lucene.codecs.KnnVectorsFormat
org.apache.lucene.backward_codecs.lucene92.Lucene92HnswVectorsFormat

All Implemented Interfaces:
  `NamedSPILoader.NamedSPI`

public class Lucene92HnswVectorsFormat extends KnnVectorsFormat
Lucene 9.2 vector format, which encodes numeric vector values and an optional associated graph connecting the documents having values. The graph is used to power HNSW search. The format consists of three files:

## .vec (vector data) file

For each field:

- Floating-point vector data ordered by field, document ordinal, and vector dimension. The floats are stored in little-endian byte order
- DocIds encoded by `IndexedDISI.writeBitSet(DocIdSetIterator, IndexOutput, byte)`, note that only in sparse case
- OrdToDoc was encoded by `DirectMonotonicWriter`, note that only in sparse case

## .vex (vector index)

Stores graphs connecting the documents for each field organized as a list of nodes' neighbours as following:

- For each level:
  - For each node:
    - [int32] the number of neighbor nodes
    - array[int32] the neighbor ordinals
    - array[int32] padding if the number of the node's neighbors is less than the maximum number of connections allowed on this level. Padding is equal to ((maxConnOnLevel – the number of neighbours) * 4) bytes.

## .vem (vector metadata) file

For each field:

- [int32] field number
- [int32] vector similarity function ordinal
- [vlong] offset to this field's vectors in the .vec file
- [vlong] length of this field's vectors, in bytes
- [vlong] offset to this field's index in the .vex file
- [vlong] length of this field's index data, in bytes
- [int] dimension of this field's vectors
- [int] the number of documents having values for this field
- [int8] if equals to -1, dense – all documents have values for a field. If equals to 0, sparse – some documents missing values.
- DocIds were encoded by `IndexedDISI.writeBitSet(DocIdSetIterator, IndexOutput, byte)`
- OrdToDoc was encoded by `DirectMonotonicWriter`, note that only in sparse case
- [int] the maximum number of connections (neighbours) that each node can have
- [int] number of levels in the graph
- Graph nodes by level. For each level
  - [int] the number of nodes on this level
  - array[int] for levels greater than 0 list of nodes on this level, stored as the the level 0th nodes ordinals.

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_BEAM_WIDTH`
  Default number of the size of the queue maintained while searching during a graph construction.
  `static final int`
  `DEFAULT_MAX_CONN`
  Default number of maximum connections per node

  ### Fields inherited from class org.apache.lucene.codecs.KnnVectorsFormat

  `DEFAULT_MAX_DIMENSIONS, EMPTY`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Lucene92HnswVectorsFormat()`
  A constructor for vectors format with default parameters
  `Lucene92HnswVectorsFormat(int maxConn, int beamWidth)`
  Constructs a format for reading old indexes

- ## Method Summary

  Modifier and Type
  Method
  Description
  `KnnVectorsReader`
  `fieldsReader(SegmentReadState state)`
  `KnnVectorsWriter`
  `fieldsWriter(SegmentWriteState state)`
  `final int`
  `getMaxDimensions(String fieldName)`
  `String`
  `toString()`

  ### Methods inherited from class org.apache.lucene.codecs.KnnVectorsFormat

  `availableKnnVectorsFormats, forName, getName, reloadKnnVectorsFormat`

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

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

- ## Field Details

  - ### DEFAULT_MAX_CONN

    public static final int DEFAULT_MAX_CONN
    Default number of maximum connections per node
    See Also:
      - Constant Field Values

  - ### DEFAULT_BEAM_WIDTH

    public static final int DEFAULT_BEAM_WIDTH
    Default number of the size of the queue maintained while searching during a graph construction.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Lucene92HnswVectorsFormat

    public Lucene92HnswVectorsFormat()
    A constructor for vectors format with default parameters

  - ### Lucene92HnswVectorsFormat

    public Lucene92HnswVectorsFormat(int maxConn, int beamWidth)
    Constructs a format for reading old indexes

- ## Method Details

  - ### fieldsWriter

    public KnnVectorsWriter fieldsWriter(SegmentWriteState state) throws IOException
    Specified by:
      `fieldsWriter` in class `KnnVectorsFormat`
    Throws:
      `IOException`

  - ### fieldsReader

    public KnnVectorsReader fieldsReader(SegmentReadState state) throws IOException
    Specified by:
      `fieldsReader` in class `KnnVectorsFormat`
    Throws:
      `IOException`

  - ### getMaxDimensions

    public final int getMaxDimensions(String fieldName)
    Specified by:
      `getMaxDimensions` in class `KnnVectorsFormat`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`