USearch Vector Search Engine

2.24.0 · active · verified Tue Apr 14

USearch is a smaller and faster single-file vector search engine from Unum, offering high-performance approximate nearest neighbor search. It is compact and broadly compatible, focusing on user-defined metrics and fewer dependencies. It follows a rapid release cadence, often with monthly or bi-monthly updates, incorporating bug fixes, performance improvements, and new language bindings across its C++, Python, JavaScript, Rust, Java, Objective-C, Swift, C#, GoLang, and Wolfram APIs.

Warnings

gotcha Earlier versions of USearch (e.g., around v2.21.x) exhibited race conditions and bugs related to concurrent `add()` and `update()` operations, potentially leading to unreachable nodes in the graph or integer underflows. While some fixes were applied (v2.21.2, v2.21.4), new issues like 'Concurrent add() creates nodes unreachable by search()' can still occur, indicating ongoing development for full concurrent stability.
Fix: Ensure you are on the latest stable version of USearch. For critical concurrent writes, review release notes and consider sequential operations or implementing custom synchronization mechanisms if issues persist.
gotcha While USearch supports user-defined metrics, passing Python callable functions directly to the engine for distance calculations can incur a performance penalty due to Python's Global Interpreter Lock (GIL) and language boundary overhead.
Fix: For performance-critical user-defined metrics, consider JIT compilation using libraries like Numba or integrating C/C++ functions via `cppyy` to compile and pass native code to the USearch engine.
breaking Python 3.14 support was explicitly added in USearch v2.23.0. Users of Python 3.14 (or newer pre-release versions) attempting to use USearch versions older than 2.23.0 may encounter compatibility issues or unexpected behavior.
Fix: Upgrade to USearch v2.23.0 or newer to ensure compatibility and full support for Python 3.14 and subsequent versions.
gotcha Results from high-performance numerical libraries like USearch can occasionally show minor differences across different operating systems, compilers, or even between runs on the same system. This is typically due to subtle variations in floating-point arithmetic rounding errors and tie-breaking algorithms, which are often non-deterministic across different environments.
Fix: For applications requiring absolute reproducibility, consider fixing the environment (OS, compiler, library versions) and carefully testing. Understand that minor variations in distances are generally expected within numerical tolerance for Approximate Nearest Neighbor (ANN) search.
gotcha Specific platform-dependent fixes (e.g., `mmap` flags for FreeBSD, compilation errors in Qt environments, Pearson correlation negative denominator fix) are frequently rolled into minor releases. Users operating on less common environments or specific setups might encounter subtle bugs or compilation issues with slightly older USearch versions.
Fix: Always use the latest stable version of USearch, especially if encountering platform-specific issues or compilation errors, as these are actively addressed in ongoing releases.

Install

pip install usearch numpy Install with NumPy

Imports

Index
```
from usearch.index import Index
```
Matches
```
from usearch.index import Matches
```

Quickstart

This quickstart demonstrates how to initialize a USearch index, add vectors with keys, perform a similarity search to find nearest neighbors, and retrieve vectors by their keys. It uses `numpy` for vector creation and manipulation.

import numpy as np
from usearch.index import Index, Matches

# Initialize an index for 3-dimensional vectors using cosine similarity
index = Index(
    ndim=3,
    metric='cos', # Options include 'l2sq', 'haversine', 'ip' (inner product)
    dtype='f32',  # Quantization to 'f16' (half-precision) or 'i8' (int8) for efficiency
    connectivity=16,
    expansion_add=128,
    expansion_search=64
)

# Create some example vectors
vector1 = np.array([0.2, 0.6, 0.4], dtype=np.float32)
vector2 = np.array([0.1, 0.7, 0.3], dtype=np.float32)
vector3 = np.array([0.9, 0.1, 0.5], dtype=np.float32)

# Add vectors to the index with unique keys
index.add(key=42, vector=vector1)
index.add(key=43, vector=vector2)
index.add(key=44, vector=vector3)

print(f"Index contains {len(index)} vectors.")

# Query the index for the 2 nearest neighbors of vector1
query_vector = np.array([0.21, 0.61, 0.41], dtype=np.float32)
matches: Matches = index.search(query_vector, 2)

print(f"Found {len(matches)} matches for the query:")
for i, match in enumerate(matches):
    print(f"  Match {i+1}: Key={match.key}, Distance={match.distance:.4f}")

# Access a vector by key
retrieved_vector = index[42]
print(f"Retrieved vector for key 42: {retrieved_vector}")
assert np.allclose(retrieved_vector, vector1)

view raw JSON →