USearch::Index
High-level wrapper for a USearch HNSW index.
The index stores vectors and allows fast approximate nearest neighbor search. Each vector is associated with a 64-bit key (typically your database row ID).
Constants
Default HNSW connectivity parameter (edges per node).
Default expansion factor during index construction.
Default expansion factor during search.
Constructors
Loads an index from a byte buffer.
The buffer is copied, so you can free it after this call.
Loads an index from a file.
The file must have been saved with #save. You must provide the
dimensions since they're needed to create the index before loading.
Creates a new empty index.
dimensions: Vector dimensionality (must match all vectors added)metric: Distance metric (default: cosine similarity)quantization: Storage precision (default: f16 for memory efficiency)connectivity: HNSW M parameter (higher = more accurate, more memory)expansion_add: ef_construction parameterexpansion_search: ef_search parametermulti: Allow multiple vectors per key
Memory-maps an index from a file (read-only, memory efficient).
The index is not loaded into memory but accessed directly from disk. This is useful for large indexes that don't fit in RAM.
Views an index from a byte buffer (zero-copy, read-only).
IMPORTANT: The bytes buffer must remain valid for the lifetime of the index. Do not modify or free the buffer while the index is in use.
Class methods
Computes distance between two vectors without an index.
Reads metadata from a saved index file without loading it.
Useful for inspecting index properties before deciding to load.
Reads metadata from a serialized index buffer without loading it.
Instance methods
Adds a vector to the index.
key: Unique identifier for this vector (e.g., database row ID)vector: The vector data (must match index dimensions)
Vectors are passed as Float32 and converted to the index's quantization format.
Returns the number of vectors for a key (useful in multi-mode).
In single-mode, returns 1 if key exists, 0 otherwise.
Sets the expansion factor for add operations.
Higher values = better graph quality but slower indexing. Default is 128.
Sets the expansion factor for search operations.
Higher values = more accurate but slower. Default is 64.
Searches for the k nearest neighbors with a filter predicate.
query: The query vector (must match index dimensions)k: Maximum number of neighbors to return&filter: Block that receives a key and returns true to include it
Example:
# Only return vectors with even keys
results = index.filtered_search(query, k: 10) { |key| key.even? }
# Only return vectors in a specific set
valid_ids = Set{1_u64, 5_u64, 10_u64}
results = index.filtered_search(query, k: 10) { |key| valid_ids.includes?(key) }Ensures the index is closed when garbage collected. Exceptions are swallowed since finalizers run during GC.
Retrieves the vector data for a key.
Returns nil if the key doesn't exist.
Searches for the k nearest neighbors to a query vector.
query: The query vector (must match index dimensions)k: Number of neighbors to return (default: 10)
Returns an array of SearchResult with keys and distances, sorted by distance.
Sets a custom distance metric function (advanced).
The callback receives two raw vector pointers and returns a distance. You must know the vector dimensions and handle the pointer arithmetic.
NOTE: The callback does not receive state, so you cannot use closures that capture variables. Use module-level functions or constants.
Serializes the index to a byte buffer.
Returns a new Bytes containing the serialized index.