HNSW Indexes

As explained in the Indexes page, the HNSW index is ideally suited for fast approximate nearest neighbor search in high-dimensional spaces, delivering an efficient balance between query speed, result accuracy, and scalability when handling large-scale datasets.

The HNSW index is constructed incrementally: each incoming vector is assigned a random maximum layer (typically drawn from a geometric distribution) and inserted into the graph starting from that level down to layer zero. For a 3D example, consider the vector v = [2.0, 1.5, 3.0]. The algorithm first performs a greedy search from the top layers using Euclidean distance to navigate toward the target region, then inserts the node at its designated level and connects it to its M nearest neighbors on each layer, applying a connection heuristic that prunes excessive links to prevent "hub" formation. Repeating this for all data points creates a multi-layer hierarchy where upper layers serve as long-range "highways" for fast cluster traversal, while layer zero forms a dense local graph, collectively enabling logarithmic query complexity and highly scalable construction.

During search, a query is introduced to the graph via a fixed entry point on the highest layer. Suppose we need to find the nearest neighbors for the query q = [1.9, 1.6, 3.2]. The algorithm greedily moves to the closest neighbor on the current layer; when no closer node can be found, it drops to the next lower layer and repeats the process until it reaches layer zero. At the base layer, an expanded search is launched using the ef_search parameter (e.g., ef_search=10): a priority queue maintains candidate nodes, iteratively exploring their neighbors, sorting them by distance to q, and ultimately returning the k closest vectors. In our 3D scenario, this approach locates the region around [2.0, 1.5, 3.0] with just a few dozen distance calculations, delivering highly accurate approximate results without requiring an exhaustive scan of the entire space.

When working with the HNSW index, the choice of distance metric critically impacts search quality:

• L2 distance (Euclidean metric) measures the straight-line geometric distance between points and is ideal for tasks where absolute proximity in space matters, such as clustering or duplicate detection.
• Cosine similarity evaluates the cosine of the angle between vectors while ignoring their magnitude, making it optimal for text embeddings and recommendation systems where directionality is more important than scale.
• Inner Product (dot product) excels in scenarios where signal "strength" or "weight" is paramount-for example, in neural recommendation models with normalized vectors or when searching over probability densities.
• Manhattan distance (L1 norm) sums the absolute differences across dimensions and is better suited for sparse or categorical data, as well as cases where outliers along individual features should not disproportionately influence the final similarity score.

When configuring the HNSW index, the key parameters are DIM, M, and space. DIM specifies the vector dimensionality and must strictly match the input data: a mismatch will cause errors, while excessive dimensionality increases memory consumption and slows down search without improving accuracy. M defines the maximum number of connections per node on each graph layer: higher values (e.g., 32-64) improve recall and navigation robustness but increase memory footprint and construction time; lower values (8-16) yield a more compact index but may reduce search quality. The space parameter selects the distance metric (l2, cosine, ip, manhattan) and should align with the data characteristics and task requirements - for instance, cosine for text embeddings, l2 for geometric coordinates.

Two dynamic parameters control search width: ef_construct and ef_search. ef_construct sets the candidate pool size during index construction: higher values (200-400) produce a higher-quality graph and better final recall but slow down indexing; lower values speed up construction but may result in suboptimal connections. ef_search controls the beam width during query time: increasing it (e.g., to 50-100) improves result completeness at the cost of higher latency; for interactive scenarios, a balanced value (10-30) is often preferred. Both parameters enable flexible tuning of the speed-accuracy trade-off after the index is built, without requiring reconstruction.

Vamana(DiskANN) Indexes

Unlike the multi-level hierarchical structure of HNSW, the Vamana index is constructed as a single-level graph with iterative edge optimization, which reduces memory overhead and accelerates index construction. By leveraging the alpha parameter for strict edge selection, Vamana delivers comparable search accuracy with lower resource consumption, whereas HNSW remains preferable in scenarios where maximum query speed is critical, thanks to its denser multi-level navigation.

Vamana conceptually uses the same core parameters as HNSW but adopts different naming conventions adapted for its single-level architecture. The M parameter (maximum number of connections) corresponds to R in Vamana, ef_construction maps to L (candidate list size during graph construction), and ef_search corresponds to L_search (search width). The distance metric type (L2, Cosine, IP, Manhattan) and vector dimensionality (DIM) remain identical, as they are dictated by the data itself. Unlike HNSW, Vamana does not employ a multi-level hierarchy and instead introduces a unique alpha parameter that controls graph density and enforces stricter edge pruning during structure optimization.

Note that the public index type name is hnsw in static schema and HNSW in SQL/wrappers, and this name is used for both the HNSW algorithm and Vamana. The vamana_alpha parameter selects the algorithm: vamana_alpha = 0 (default) chooses HNSW, while any positive value chooses Vamana.

When vamana_alpha is set to -1 for a Vamana index, edge pruning is disabled entirely. This eliminates the selectivity that the alpha parameter normally provides, resulting in a denser graph with more connections per node. While this configuration reduces search performance, it enables cursor traversal over the full set of indexed values, which is otherwise not possible with a pruned Vamana graph.

The vamana_build_method parameter specifies the strategy for selecting the starting point during Vamana graph construction. By default, this parameter is set to "incremental" (or "default"), in which case the first inserted point becomes the root. Two alternative values are available: "medoid" and "centroid". With "medoid", the root point is selected in a two-pass process based on the existing values in the table. With "centroid", an artificial central point — computed as the mean of all coordinates — is created and used as the anchor vertex for graph construction.