Package org.apache.lucene.util.hnsw

## Class HnswGraphBuilder

- java.lang.Object
- - org.apache.lucene.util.hnsw.HnswGraphBuilder

- All Implemented Interfaces:
    `HnswBuilder`
  Direct Known Subclasses:
    `InitializedHnswGraphBuilder`

      public class HnswGraphBuilder
      extends Object
      implements HnswBuilder

  Builder for HNSW graph. See `HnswGraph` for a gloss on the algorithm and the meaning of the hyper-parameters.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `HnswGraphBuilder.GraphBuilderKnnCollector` | A restricted, specialized knnCollector that can be used when building a graph.

  - ### 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
    `protected OnHeapHnswGraph` | `hnsw` |
    `static String` | `HNSW_COMPONENT` | A name for the HNSW component for the info-stream *
    `static long` | `randSeed` | Random seed for level generation; public to expose for testing *

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `HnswGraphBuilder​(RandomVectorScorerSupplier scorerSupplier, int M, int beamWidth, long seed, int graphSize)` | Reads all the vectors from vector values, builds a graph connecting them by their dense ordinals, using the given hyperparameter settings, and returns the resulting graph.
    `protected` | `HnswGraphBuilder​(RandomVectorScorerSupplier scorerSupplier, int M, int beamWidth, long seed, OnHeapHnswGraph hnsw)` |
    `protected` | `HnswGraphBuilder​(RandomVectorScorerSupplier scorerSupplier, int M, int beamWidth, long seed, OnHeapHnswGraph hnsw, HnswGraphSearcher graphSearcher)` | Reads all the vectors from vector values, builds a graph connecting them by their dense ordinals, using the given hyperparameter settings, and returns the resulting graph.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addGraphNode​(int node)` | Inserts a doc with vector value to the graph
    `protected void` | `addVectors​(int minOrd, int maxOrd)` | add vectors in range [minOrd, maxOrd)
    `OnHeapHnswGraph` | `build​(int maxOrd)` | Adds all nodes to the graph up to the provided `maxOrd`.
    `static HnswGraphBuilder` | `create​(RandomVectorScorerSupplier scorerSupplier, int M, int beamWidth, long seed)` |
    `static HnswGraphBuilder` | `create​(RandomVectorScorerSupplier scorerSupplier, int M, int beamWidth, long seed, int graphSize)` |
    `OnHeapHnswGraph` | `getGraph()` |
    `void` | `setInfoStream​(InfoStream infoStream)` | Set info-stream to output debugging information

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, 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

    - #### HNSW_COMPONENT

          public static final String HNSW_COMPONENT

      A name for the HNSW component for the info-stream *
      See Also:
        Constant Field Values

    - #### randSeed

          public static long randSeed

      Random seed for level generation; public to expose for testing *

    - #### hnsw

          protected final OnHeapHnswGraph hnsw

  - ### Constructor Detail

    - #### HnswGraphBuilder

          protected HnswGraphBuilder​(RandomVectorScorerSupplier scorerSupplier,
                                     int M,
                                     int beamWidth,
                                     long seed,
                                     int graphSize)
                              throws IOException

      Reads all the vectors from vector values, builds a graph connecting them by their dense ordinals, using the given hyperparameter settings, and returns the resulting graph.
      Parameters:
        `scorerSupplier` - a supplier to create vector scorer from ordinals.
        `M` - – graph fanout parameter used to calculate the maximum number of connections a node can have – M on upper layers, and M * 2 on the lowest level.
        `beamWidth` - the size of the beam search to use when finding nearest neighbors.
        `seed` - the seed for a random number generator used during graph construction. Provide this to ensure repeatable construction.
        `graphSize` - size of graph, if unknown, pass in -1
      Throws:
        `IOException`

    - #### HnswGraphBuilder

          protected HnswGraphBuilder​(RandomVectorScorerSupplier scorerSupplier,
                                     int M,
                                     int beamWidth,
                                     long seed,
                                     OnHeapHnswGraph hnsw)
                              throws IOException

      Throws:
        `IOException`

    - #### HnswGraphBuilder

          protected HnswGraphBuilder​(RandomVectorScorerSupplier scorerSupplier,
                                     int M,
                                     int beamWidth,
                                     long seed,
                                     OnHeapHnswGraph hnsw,
                                     HnswGraphSearcher graphSearcher)
                              throws IOException

      Reads all the vectors from vector values, builds a graph connecting them by their dense ordinals, using the given hyperparameter settings, and returns the resulting graph.
      Parameters:
        `scorerSupplier` - a supplier to create vector scorer from ordinals.
        `M` - – graph fanout parameter used to calculate the maximum number of connections a node can have – M on upper layers, and M * 2 on the lowest level.
        `beamWidth` - the size of the beam search to use when finding nearest neighbors.
        `seed` - the seed for a random number generator used during graph construction. Provide this to ensure repeatable construction.
        `hnsw` - the graph to build, can be previously initialized
      Throws:
        `IOException`

  - ### Method Detail

    - #### create

          public static HnswGraphBuilder create​(RandomVectorScorerSupplier scorerSupplier,
                                                int M,
                                                int beamWidth,
                                                long seed)
                                         throws IOException

      Throws:
        `IOException`

    - #### create

          public static HnswGraphBuilder create​(RandomVectorScorerSupplier scorerSupplier,
                                                int M,
                                                int beamWidth,
                                                long seed,
                                                int graphSize)
                                         throws IOException

      Throws:
        `IOException`

    - #### build

          public OnHeapHnswGraph build​(int maxOrd)
                                throws IOException

      Description copied from interface: `HnswBuilder`
      Adds all nodes to the graph up to the provided `maxOrd`.
      Specified by:
        `build` in interface `HnswBuilder`
      Parameters:
        `maxOrd` - The maximum ordinal (excluded) of the nodes to be added.
      Throws:
        `IOException`

    - #### setInfoStream

          public void setInfoStream​(InfoStream infoStream)

      Description copied from interface: `HnswBuilder`
      Set info-stream to output debugging information
      Specified by:
        `setInfoStream` in interface `HnswBuilder`

    - #### getGraph

          public OnHeapHnswGraph getGraph()

      Specified by:
        `getGraph` in interface `HnswBuilder`

    - #### addVectors

          protected void addVectors​(int minOrd,
                                    int maxOrd)
                             throws IOException

      add vectors in range [minOrd, maxOrd)
      Throws:
        `IOException`

    - #### addGraphNode

          public void addGraphNode​(int node)
                            throws IOException

      Description copied from interface: `HnswBuilder`
      Inserts a doc with vector value to the graph
      Specified by:
        `addGraphNode` in interface `HnswBuilder`
      Throws:
        `IOException`