Documentation
¶
Overview ¶
Package vector implements approximate nearest-neighbour search using a Hierarchical Navigable Small World (HNSW) graph.
The entry type is HNSWIndex, constructed with NewHNSWIndex (dimensions, M, efConstruction, metric). It supports the MetricCosine, MetricEuclidean, and MetricDotProduct distance metrics, Insert/Search/Delete, and concurrent reads under an RWMutex (writes serialize).
Construction cost is data-dependent: ~O(N log N) for real embeddings, which cluster on a low-dimensional manifold. Uniform-random or otherwise maximal-intrinsic-dimensionality vectors degrade toward O(N²) under concentration of measure — a property of the data, not a bug. See the package benchmarks (BenchmarkHNSWInsert vs BenchmarkHNSWInsert_Clustered).
Index ¶
- Variables
- func CosineDistance(a, b []float32) (float32, error)
- func CosineSimilarity(a, b []float32) (float32, error)
- func Distance(a, b []float32, metric DistanceMetric) (float32, error)
- func DotProduct(a, b []float32) (float32, error)
- func EuclideanDistance(a, b []float32) (float32, error)
- func Magnitude(v []float32) float32
- func Normalize(v []float32) []float32
- type DistanceMetric
- type HNSWIndex
- func (h *HNSWIndex) Delete(id uint64) error
- func (h *HNSWIndex) Dimensions() int
- func (h *HNSWIndex) EfConstruction() int
- func (h *HNSWIndex) Insert(id uint64, vector []float32) error
- func (h *HNSWIndex) Len() int
- func (h *HNSWIndex) M() int
- func (h *HNSWIndex) Metric() DistanceMetric
- func (h *HNSWIndex) Search(query []float32, k int, ef int) ([]SearchResult, error)
- type SearchResult
Constants ¶
This section is empty.
Variables ¶
var ErrDimensionMismatch = fmt.Errorf("vector dimensions mismatch")
ErrDimensionMismatch is returned when vector dimensions don't match
Functions ¶
func CosineDistance ¶
CosineDistance calculates the cosine distance between two vectors Returns a value between 0 (identical) and 2 (opposite) Formula: 1 - cosine_similarity(a, b) Returns error if vector dimensions don't match
func CosineSimilarity ¶
CosineSimilarity calculates the cosine similarity between two vectors Returns a value between -1 (opposite) and 1 (identical) Formula: (a · b) / (||a|| * ||b||) Returns error if vector dimensions don't match
func Distance ¶
func Distance(a, b []float32, metric DistanceMetric) (float32, error)
Distance calculates the distance between two vectors using the specified metric Returns error if vector dimensions don't match
func DotProduct ¶
DotProduct calculates the dot product of two vectors Formula: sum(a[i] * b[i]) Returns error if vector dimensions don't match
func EuclideanDistance ¶
EuclideanDistance calculates the Euclidean (L2) distance between two vectors Formula: sqrt(sum((a[i] - b[i])^2)) Returns error if vector dimensions don't match
Types ¶
type DistanceMetric ¶
type DistanceMetric string
DistanceMetric represents the type of distance calculation
const ( MetricCosine DistanceMetric = "cosine" MetricEuclidean DistanceMetric = "euclidean" MetricDotProduct DistanceMetric = "dot_product" )
type HNSWIndex ¶
type HNSWIndex struct {
// contains filtered or unexported fields
}
HNSWIndex implements Hierarchical Navigable Small World graph for approximate nearest neighbor search
func NewHNSWIndex ¶
func NewHNSWIndex(dimensions, m, efConstruction int, metric DistanceMetric) (*HNSWIndex, error)
NewHNSWIndex creates a new HNSW index
func (*HNSWIndex) Dimensions ¶
Dimensions returns the vector dimensions
func (*HNSWIndex) EfConstruction ¶
EfConstruction returns the construction-time candidate-list size. See M.
func (*HNSWIndex) M ¶
M returns the construction parameter m (bi-directional links per node). Exposed so the index definition can be persisted and recreated identically on restart (the HNSW graph itself is not serialized; it is rebuilt from the node set on load).
func (*HNSWIndex) Metric ¶
func (h *HNSWIndex) Metric() DistanceMetric
Metric returns the distance metric used by this index
type SearchResult ¶
SearchResult represents a search result with ID and distance
Source Files