Package org.apache.lucene.backward_codecs.lucene95

## Class Lucene95HnswVectorsFormat

- java.lang.Object
- - org.apache.lucene.codecs.KnnVectorsFormat
  - - org.apache.lucene.backward_codecs.lucene95.Lucene95HnswVectorsFormat

- All Implemented Interfaces:
    `NamedSPILoader.NamedSPI`

      public class Lucene95HnswVectorsFormat
      extends KnnVectorsFormat

  Lucene 9.5 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:

  - Vector data ordered by field, document ordinal, and vector dimension. When the vectorEncoding is BYTE, each sample is stored as a single byte. When it is FLOAT32, each sample is stored as an IEEE float 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:
      - [vint] the number of neighbor nodes
      - array[vint] the delta encoded neighbor ordinals
  - After all levels are encoded memory offsets for each node's neighbor nodes encoded by `DirectMonotonicWriter` are appended to the end of the file.

  ## .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
  - [vint] 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
  - [vint] the maximum number of connections (neighbours) that each node can have
  - [vint] number of levels in the graph
  - Graph nodes by level. For each level
    - [vint] the number of nodes on this level
    - array[vint] for levels greater than 0 list of nodes on this level, stored as the level 0th delta encoded 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 int` | `DEFAULT_BEAM_WIDTH` | Default number of the size of the queue maintained while searching during a graph construction.
    `static 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
    --- | ---
    `Lucene95HnswVectorsFormat()` | Constructs a format using default graph construction parameters
    `Lucene95HnswVectorsFormat​(int maxConn, int beamWidth)` | Constructs a format using the given graph construction parameters.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `KnnVectorsReader` | `fieldsReader​(SegmentReadState state)` |
    `KnnVectorsWriter` | `fieldsWriter​(SegmentWriteState state)` |
    `int` | `getMaxDimensions​(String fieldName)` |
    `String` | `toString()` |

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

      `forName, getName`

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

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

- - ### Field Detail

    - #### 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 Detail

    - #### Lucene95HnswVectorsFormat

          public Lucene95HnswVectorsFormat()

      Constructs a format using default graph construction parameters

    - #### Lucene95HnswVectorsFormat

          public Lucene95HnswVectorsFormat​(int maxConn,
                                           int beamWidth)

      Constructs a format using the given graph construction parameters.
      Parameters:
        `maxConn` - the maximum number of connections to a node in the HNSW graph
        `beamWidth` - the size of the queue maintained during graph construction.

  - ### Method Detail

    - #### 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 int getMaxDimensions​(String fieldName)

      Overrides:
        `getMaxDimensions` in class `KnnVectorsFormat`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`