API Reference¶

This page provides a comprehensive reference for the HNSW API.

Core Types¶

Vector¶

type Vector = []float32

A Vector is a slice of float32 values representing a point in a high-dimensional space.

Node¶

type Node[K cmp.Ordered] struct {
    Key   K
    Value Vector
}

A Node represents a point in the vector space with a unique key.

Methods¶

func MakeNode[K cmp.Ordered](key K, vec Vector) Node[K]

Creates a new node with the specified key and vector.

Graph¶

type Graph[K cmp.Ordered] struct {
    // Distance is the distance function used to compare embeddings.
    Distance DistanceFunc

    // M is the maximum number of neighbors to keep for each node.
    // A good default for OpenAI embeddings is 16.
    M int

    // Ml is the level generation factor.
    // E.g., for Ml = 0.25, each layer is 1/4 the size of the previous layer.
    Ml float64

    // EfSearch is the number of nodes to consider in the search phase.
    // 20 is a reasonable default. Higher values improve search accuracy at
    // the expense of memory.
    EfSearch int
}

A Graph is a Hierarchical Navigable Small World graph that stores vectors and allows for efficient similarity search.

Constructor Functions¶

NewGraph¶

func NewGraph[K cmp.Ordered]() *Graph[K]

Creates a new graph with default parameters:

• M: 16
• Ml: 0.25
• Distance: CosineDistance
• EfSearch: 20

NewGraphWithConfig¶

func NewGraphWithConfig[K cmp.Ordered](m int, ml float64, efSearch int, distance DistanceFunc) (*Graph[K], error)

Creates a new graph with the specified parameters and validates the configuration.

Graph Methods¶

Add¶

func (g *Graph[K]) Add(nodes ...Node[K]) error

Adds one or more nodes to the graph. If a node with the same key already exists, it is replaced.

BatchAdd¶

func (g *Graph[K]) BatchAdd(nodes []Node[K]) error

Adds multiple nodes to the graph in a single operation. This is more efficient than calling Add multiple times when adding many nodes.

Search¶

func (g *Graph[K]) Search(near Vector, k int) ([]Node[K], error)

Searches for the k nearest neighbors to the query vector.

ParallelSearch¶

func (g *Graph[K]) ParallelSearch(near Vector, k int, numWorkers int) ([]Node[K], error)

Performs a parallel search for the k nearest neighbors to the query vector using the specified number of worker goroutines.

SearchWithNegative¶

func (g *Graph[K]) SearchWithNegative(near Vector, negative Vector, k int, negWeight float32) ([]Node[K], error)

Searches for vectors that are similar to the positive example (near) but dissimilar to the negative example (negative).

SearchWithNegatives¶

func (g *Graph[K]) SearchWithNegatives(near Vector, negatives []Vector, k int, negWeight float32) ([]Node[K], error)

Searches for vectors that are similar to the positive example (near) but dissimilar to multiple negative examples (negatives).

Delete¶

func (g *Graph[K]) Delete(key K) bool

Deletes a node from the graph. Returns true if the node was found and deleted.

BatchDelete¶

func (g *Graph[K]) BatchDelete(keys []K) []bool

Deletes multiple nodes from the graph in a single operation. Returns a slice of booleans indicating which nodes were found and deleted.

Lookup¶

func (g *Graph[K]) Lookup(key K) (Vector, bool)

Looks up a node by key and returns its vector. Returns false if the node is not found.

Len¶

func (g *Graph[K]) Len() int

Returns the number of nodes in the graph.

Export¶

func (g *Graph[K]) Export(w io.Writer) error

Exports the graph to the specified writer.

Import¶

func (g *Graph[K]) Import(r io.Reader) error

Imports a graph from the specified reader.

Distance Functions¶

type DistanceFunc func(a, b Vector) float32

A DistanceFunc calculates the distance between two vectors.

Built-in Distance Functions¶

CosineDistance¶

func CosineDistance(a, b Vector) float32

Calculates the cosine distance between two vectors: 1 - cosine similarity.

EuclideanDistance¶

func EuclideanDistance(a, b Vector) float32

Calculates the Euclidean (L2) distance between two vectors.

DotProductDistance¶

func DotProductDistance(a, b Vector) float32

Calculates the negative dot product between two vectors.

Extensions¶

HNSW provides several extensions that enhance its functionality:

Metadata Extension¶

The Metadata Extension allows you to store and retrieve JSON metadata alongside vectors in the graph.

import "github.com/TFMV/hnsw/hnsw-extensions/meta"

Key Types¶

type MetadataNode[K cmp.Ordered] struct {
    Node     hnsw.Node[K]
    Metadata json.RawMessage
}

type MetadataGraph[K cmp.Ordered] struct {
    Graph *hnsw.Graph[K]
    Store MetadataStore[K]
}

Constructor¶

func NewMetadataGraph[K cmp.Ordered](graph *hnsw.Graph[K], store MetadataStore[K]) *MetadataGraph[K]

Creates a new metadata graph that wraps an HNSW graph and a metadata store.

Faceted Search Extension¶

The Faceted Search extension allows you to filter search results based on facets or attributes.

import "github.com/TFMV/hnsw/hnsw-extensions/facets"

Key Types¶

type FacetedNode[K cmp.Ordered] struct {
    Node   hnsw.Node[K]
    Facets map[string]interface{}
}

type FacetedGraph[K cmp.Ordered] struct {
    Graph *hnsw.Graph[K]
    Store FacetStore[K]
}

Constructor¶

func NewFacetedGraph[K cmp.Ordered](graph *hnsw.Graph[K], store FacetStore[K]) *FacetedGraph[K]

Creates a new faceted graph that wraps an HNSW graph and a facet store.

Error Handling¶

Most methods in the HNSW API return errors that should be checked. Common errors include:

• Dimension mismatch errors when adding vectors with different dimensions
• Configuration validation errors when creating a graph with invalid parameters
• I/O errors when importing or exporting graphs

Example error handling:

err := graph.Add(node)
if err != nil {
    // Handle error
    log.Fatalf("Failed to add node: %v", err)
}