Package org.apache.lucene.codecs.lucene94

Class Lucene94HnswVectorsFormat

  • All Implemented Interfaces:
    NamedSPILoader.NamedSPI
    public final class Lucene94HnswVectorsFormat
extends KnnVectorsFormat
    Lucene 9.4 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:
        • [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 (neigbours) 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 level 0th nodes' ordinals.
    WARNING: This API is experimental and might change in incompatible ways in the next release.