Performance¶

iscc-usearch depends on a patched USearch fork (v2.23.3) tuned for ISCC-specific workloads. USearch is a fast ANNS library; the fork adds support for heavy sharding, read-mostly access patterns, and large memory-mapped indexes that ISCC indexing requires.

Patched USearch fork¶

The fork is published on PyPI as usearch-iscc with pre-built wheels for Python 3.12+ on macOS, Linux (x86_64, aarch64), and Windows (AMD64, ARM64).

Instant view() for memory-mapped indexes¶

ISCC indexing uses dozens of memory-mapped shards. Opening a 55-shard index (18 GB, 100M vectors) took ~15.3 seconds because view() performs two O(n) startup operations:

1. vectors_lookup_ population -- Pre-computes a pointer for every vector in the memory-mapped file (8 bytes per vector, ~800 MB for 100M vectors).
2. reindex_keys_() call -- Builds a hash map for key-to-slot lookups by scanning the entire HNSW graph.

Both are useful for read-write workloads but unnecessary for read-only memory-mapped shards where vectors are contiguous and offsets are computable as base + stride * slot.

Three patches in index_dense.hpp and lib.cpp:

• Computed offsets for view mode: Replaces the vectors_lookup_ pointer table with stride-based arithmetic (base + stride * slot). This removes the O(n) loop and per-vector pointer memory overhead.
• Lazy key reindexing: Defers slot_lookup_ population to first access via double-checked locking (std::atomic<bool> + mutex). view() returns immediately; key reindexing happens on the first contains(), get(), or count() call.
• GIL release in Python bindings: Wraps load() and view() with py::gil_scoped_release (when no progress callback is active), so multiple shards can load concurrently from threads.

View benchmark results (stock USearch vs. ISCC fork)¹¶

Additional patches¶

The fork also fixes edge cases found in ISCC workloads. These have been reported upstream and may be resolved in future USearch releases.

• Index.get() for missing keys (#494) -- get() on non-existent keys returns uninitialized memory. The patch adds a contains() check and returns None for missing keys.
• Index.search(count=0) guard -- search() with count=0 triggers a zero-width array allocation. The patch adds validation at both Python and C++ levels.
• serialized_length Python binding (#683) -- pybind11 cannot resolve the default serialization_config_t argument. The patch wraps it with a lambda calling the no-argument overload.
• IndexedKeys.__array__ NumPy 2.0 compatibility -- Missing copy keyword parameter causes DeprecationWarning in NumPy 2.0. The patch adds and honors the parameter.

iscc-usearch optimizations¶

Bloom filter for key rejection¶

ShardedIndex has a scalable bloom filter for O(1) rejection of non-existent keys in get(), contains(), and count(). Without it, checking whether a key exists requires querying every shard sequentially.

Design:

• Chains multiple fixed-size bloom filters with progressively tighter false positive rates (geometric series with r=0.5) to support unlimited growth.
• Initial capacity: 10M elements, doubling per filter.
• Default false positive rate: 1%.
• Batch operations delegate to native Rust (fastbloom-rs) for throughput.
• Checks newest filter first (most likely location for recent keys).

Bloom filter vs. native key lookups²¶

Even with the patched fork's efficient key lookups in view mode, the bloom filter is 3-50x faster for non-existent key rejection. Without bloom, miss latency scales linearly with shard count because every shard must be checked. With bloom, miss latency stays constant at ~1 us regardless of shard count.

Single key contains() -- non-existent keys (bloom's strength):

Single key contains() -- existing keys (bloom overhead):

Batch get() (100 keys) -- non-existent keys:

For existing keys, the bloom filter adds ~1.3-1.8x overhead at low shard counts but becomes neutral or faster at higher counts where Python-level shard iteration dominates. The bloom filter is enabled by default and recommended for all sharded indexes.

Sharded index architecture¶

HNSW graph construction slows as the graph grows. A single USearch Index averages ~11.7K vectors/sec over 1M inserts, with throughput dropping as the graph grows. Sharding resets the curve: each shard stays small, holding ~13K vectors/sec throughout.

Vectorized search merging¶

Multi-shard search results are merged with vectorized NumPy operations:

• np.concatenate stacks results from all shards.
• np.argsort(axis=1) sorts each query row independently.
• Advanced indexing gathers sorted keys and distances without per-query iteration.
• Radius filtering is applied as a vectorized mask across the entire batch.

A fast path skips allocation when only one shard returns results.

Shard discovery caching¶

Filesystem glob results (shard_*.usearch) are cached and only invalidated when shards are created or rotated. This avoids repeated directory scans on every operation.

Lazy key and vector iterators¶

ShardedIndexedKeys and ShardedIndexedVectors iterate lazily across all shards. Keys and vectors are yielded shard-by-shard without loading everything into memory, so you can iterate over 100M+ vectors without proportional RAM usage.

Numba JIT compilation¶

• @cfunc metric: The NPHD metric is compiled to a C-callable function pointer passed directly to USearch's C++ core, bypassing Python callback overhead on every distance computation.
• @njit(cache=True) padding: pad_vectors and unpad_vectors are compiled with result caching, so the compilation cost is paid only once.

Fast-path key lookups¶

get() and contains() check shards in priority order to minimize iterations:

1. Bloom filter -- O(1) rejection if the key definitely doesn't exist.
2. Active shard -- Checked first since recent inserts are most likely here.
3. View shards -- Iterated with early termination once all requested keys are found.

Performance characteristics¶

Query latency vs. shard count¶

Query latency scales linearly with shard count because each shard is searched independently and results are merged:

256-bit binary vectors, Hamming distance, M=16, efConstruction=32, ef=512, 128 MB shards.³

Cold start¶

55 shards (~315 MB each, 18 GB total, 100M vectors).

Tuning guidance¶

Shard size¶

HNSW parameters¶

The defaults work well for most workloads. Increase expansion_search if recall is too low; increase connectivity for better recall at the cost of memory.