Overview#

USearch

Smaller & Faster Single-File
Similarity Search Engine for Vectors & 🔜 Texts


Discord     LinkedIn     Twitter     Blog     GitHub

Spatial • Binary • Probabilistic • User-Defined Metrics
C++ 11Python 3JavaScriptJavaRustC 99Objective-CSwiftC#GoLangWolfram
Linux • MacOS • Windows • iOS • WebAssembly • SQLite3


Technical Insights and related articles:

Comparison with FAISS#

FAISS is a widely recognized standard for high-performance vector search engines. USearch and FAISS both employ the same HNSW algorithm, but they differ significantly in their design principles. USearch is compact and broadly compatible without sacrificing performance, primarily focusing on user-defined metrics and fewer dependencies.

FAISS

USearch

Improvement

Indexing time ⁰

100 Million 96d f32, f16, i8 vectors

2.6 · 2.6 · 2.6 h

0.3 · 0.2 · 0.2 h

9.6 · 10.4 · 10.7 x

100 Million 1536d f32, f16, i8 vectors

5.0 · 4.1 · 3.8 h

2.1 · 1.1 · 0.8 h

2.3 · 3.6 · 4.4 x

Codebase length ¹

84 K SLOC

3 K SLOC

maintainable

Supported metrics ²

9 fixed metrics

any metric

extendible

Supported languages ³

C++, Python

10 languages

portable

Supported ID types ⁴

32-bit, 64-bit

32-bit, 40-bit, 64-bit

efficient

Required dependencies ⁵

BLAS, OpenMP

light-weight

Bindings ⁶

SWIG

Native

low-latency

Python binding size ⁷

~ 10 MB

< 1 MB

deployable

Tested on Intel Sapphire Rapids, with the simplest inner-product distance, equivalent recall, and memory consumption while also providing far superior search speed. ¹ A shorter codebase of usearch/ over faiss/ makes the project easier to maintain and audit. ² User-defined metrics allow you to customize your search for various applications, from GIS to creating custom metrics for composite embeddings from multiple AI models or hybrid full-text and semantic search. ³ With USearch, you can reuse the same preconstructed index in various programming languages. ⁴ The 40-bit integer allows you to store 4B+ vectors without allocating 8 bytes for every neighbor reference in the proximity graph. ⁵ Lack of obligatory dependencies makes USearch much more portable. ⁶ Native bindings introduce lower call latencies than more straightforward approaches. ⁷ Lighter bindings make downloads and deployments faster.

Base functionality is identical to FAISS, and the interface must be familiar if you have ever investigated Approximate Nearest Neighbors search:

$ pip install numpy usearch

import numpy as np
from usearch.index import Index

index = Index(ndim=3)

vector = np.array([0.2, 0.6, 0.4])
index.add(42, vector)

matches = index.search(vector, 10)

assert matches[0].key == 42
assert matches[0].distance <= 0.001
assert np.allclose(index[42], vector, atol=0.1) # Ensure high tolerance in mixed-precision comparisons

More settings are always available, and the API is designed to be as flexible as possible.

index = Index(
    ndim=3, # Define the number of dimensions in input vectors
    metric='cos', # Choose 'l2sq', 'haversine' or other metric, default = 'ip'
    dtype='f32', # Quantize to 'f16' or 'i8' if needed, default = 'f32'
    connectivity=16, # Optional: Limit number of neighbors per graph node
    expansion_add=128, # Optional: Control the recall of indexing
    expansion_search=64, # Optional: Control the quality of the search
    multi=False, # Optional: Allow multiple vectors per key, default = False
)

Serialization & Serving Index from Disk#

USearch supports multiple forms of serialization:

  • Into a file defined with a path.

  • Into a stream defined with a callback, serializing or reconstructing incrementally.

  • Into a buffer of fixed length or a memory-mapped file that supports random access.

The latter allows you to serve indexes from external memory, enabling you to optimize your server choices for indexing speed and serving costs. This can result in 20x cost reduction on AWS and other public clouds.

index.save("index.usearch")

loaded_copy = index.load("index.usearch")
view = Index.restore("index.usearch", view=True)

other_view = Index(ndim=..., metric=...)
other_view.view("index.usearch")

Indexes for Multi-Index Lookups#

For larger workloads targeting billions or even trillions of vectors, parallel multi-index lookups become invaluable. Instead of constructing one extensive index, you can build multiple smaller ones and view them together.

from usearch.index import Indexes

multi_index = Indexes(
    indexes: Iterable[usearch.index.Index] = [...],
    paths: Iterable[os.PathLike] = [...],
    view: bool = False,
    threads: int = 0,
)
multi_index.search(...)

Clustering#

Once the index is constructed, USearch can perform K-Nearest Neighbors Clustering much faster than standalone clustering libraries, like SciPy, UMap, and tSNE. Same for dimensionality reduction with PCA. Essentially, the Index itself can be seen as a clustering, allowing iterative deepening.

clustering = index.cluster(
    min_count=10, # Optional
    max_count=15, # Optional
    threads=..., # Optional
)

# Get the clusters and their sizes
centroid_keys, sizes = clustering.centroids_popularity

# Use Matplotlib to draw a histogram
clustering.plot_centroids_popularity()

# Export a NetworkX graph of the clusters
g = clustering.network

# Get members of a specific cluster
first_members = clustering.members_of(centroid_keys[0])

# Deepen into that cluster, splitting it into more parts, all the same arguments supported
sub_clustering = clustering.subcluster(min_count=..., max_count=...)

The resulting clustering isn’t identical to K-Means or other conventional approaches but serves the same purpose. Alternatively, using Scikit-Learn on a 1 Million point dataset, one may expect queries to take anywhere from minutes to hours, depending on the number of clusters you want to highlight. For 50’000 clusters, the performance difference between USearch and conventional clustering methods may easily reach 100x.

Joins, One-to-One, One-to-Many, and Many-to-Many Mappings#

One of the big questions these days is how AI will change the world of databases and data management. Most databases are still struggling to implement high-quality fuzzy search, and the only kind of joins they know are deterministic. A join differs from searching for every entry, requiring a one-to-one mapping banning collisions among separate search results.

Exact Search

Fuzzy Search

Semantic Search ?

Exact Join

Fuzzy Join ?

Semantic Join ??

Using USearch, one can implement sub-quadratic complexity approximate, fuzzy, and semantic joins. This can be useful in any fuzzy-matching tasks common to Database Management Software.

men = Index(...)
women = Index(...)
pairs: dict = men.join(women, max_proposals=0, exact=False)

User-Defined Functions#

While most vector search packages concentrate on just a few metrics - “Inner Product distance” and “Euclidean distance,” USearch extends this list to include any user-defined metrics. This flexibility allows you to customize your search for various applications, from computing geospatial coordinates with the rare Haversine distance to creating custom metrics for composite embeddings from multiple AI models.

USearch: Vector Search Approaches

Unlike older approaches indexing high-dimensional spaces, like KD-Trees and Locality Sensitive Hashing, HNSW doesn’t require vectors to be identical in length. They only have to be comparable. So you can apply it in obscure applications, like searching for similar sets or fuzzy text matching, using GZip as a distance function.

Memory Efficiency, Downcasting, and Quantization#

Training a quantization model and dimension-reduction is a common approach to accelerate vector search. Those, however, are only sometimes reliable, can significantly affect the statistical properties of your data, and require regular adjustments if your distribution shifts. Instead, we have focused on high-precision arithmetic over low-precision downcasted vectors. The same index, and add and search operations will automatically down-cast or up-cast between f64_t, f32_t, f16_t, i8_t, and single-bit representations. You can use the following command to check, if hardware acceleration is enabled:

$ python -c 'from usearch.index import Index; print(Index(ndim=768, metric="cos", dtype="f16").hardware_acceleration)'
> avx512+f16
$ python -c 'from usearch.index import Index; print(Index(ndim=166, metric="tanimoto").hardware_acceleration)'
> avx512+popcnt

Using smaller numeric types will save you RAM needed to store the vectors, but you can also compress the neighbors lists forming our proximity graphs. By default, 32-bit uint32_t is used to enumerate those, which is not enough if you need to address over 4 Billion entries. For such cases we provide a custom uint40_t type, that will still be 37.5% more space-efficient than the commonly used 8-byte integers, and will scale up to 1 Trillion entries.

USearch uint40_t support

Functionality#

By now, the core functionality is supported across all bindings. Broader functionality is ported per request. In some cases, like Batch operations, feature parity is meaningless, as the host language has full multi-threading capabilities and the USearch index structure is concurrent by design, so the users can implement batching/scheduling/load-balancing in the most optimal way for their applications.

C++ 11

Python 3

C 99

Java

JavaScript

Rust

GoLang

Swift

Add, search, remove

Save, load, view

User-defined metrics

Batch operations

Joins

Variable-length vectors

4B+ capacities

Application Examples#

USearch + POI Coordinates = GIS Applications… on iOS?#

USearch Maps with SwiftUI

With Objective-C and Swift iOS bindings, USearch can be easily used in mobile applications. The SwiftVectorSearch project illustrates how to build a dynamic, real-time search system on iOS. In this example, we use 2-dimensional vectors—encoded as latitude and longitude—to find the closest Points of Interest (POIs) on a map. The search is based on the Haversine distance metric but can easily be extended to support high-dimensional vectors.

Integrations#

Citations#

@software{Vardanian_USearch_2023,
doi = {10.5281/zenodo.7949416},
author = {Vardanian, Ash},
title = {{USearch by Unum Cloud}},
url = {https://github.com/unum-cloud/usearch},
version = {2.9.2},
year = {2023},
month = oct,
}