Skip to content

RaBitQ Library 0.6.0

This release adds concurrent Python index searches, configurable IVF centroid routing, and 32-coordinate padding. It upgrades Eigen to 5.0.1 and stops propagating optimization flags to CMake consumers.

Upgrading from 0.5.2

Python concurrency

IvfIndex, HnswIndex, and SymqgIndex release the GIL during native search, construction, updates, and file I/O. Searches, saves, and property reads may run together. Updates require exclusive access; conflicts immediately raise RuntimeError("Index is busy: conflicting operation in progress"). Applications that relied on the GIL to serialize access must coordinate updates.

Keep input arrays unchanged until each call returns. HNSW's Python ef remains optional; SymphonyQG's remains required. With a Python thread pool, consider num_threads=1 to avoid multiplying native worker pools. Concurrent saves need distinct paths, including sidecars. See the threading contract.

C++ callers must synchronize mutations themselves. SymphonyQG adds search_batch_with_ef() for per-call windows; existing search APIs remain available.

IVF routing and saved files

Python's initializer accepts "auto", "flat", "flat_rabitq", or "hnsw"; C++ provides the corresponding InitializerType. New indexes using auto select:

Number of clusters Initializer
Below 5,000 Flat
5,000–59,999 Flat RaBitQ
60,000 or more HNSW

Flat RaBitQ and HNSW routing are approximate, so rebuilding with auto can change recall and latency. To retain the previous routing policy, select Flat below 20,000 clusters and HNSW otherwise.

New IVF saves use RABQIDX1 version 2 and record the resolved initializer. Older releases cannot read these files. Current readers support legacy quantized files, raw v1 files, and RABQIDX1 v1 files, retaining historical routing rules where needed. Keep the .hnsw sidecar with HNSW-routed indexes. See the IVF format guide.

Padding and historical compatibility

New indexes and clustering pad dimensions to multiples of 32. Loading preserves the saved padding and rotation, including historical 64-coordinate padding. Older HNSW and SymphonyQG readers that require multiples of 64 cannot load new files whose stored padding is not divisible by 64.

Tests cover frozen v0.5.2 IVF, HNSW, and raw/quantized SymphonyQG files under L2 and inner product, including queries, resave/load migration, and malformed files. This coverage does not guarantee compatibility with every historical format. Keep original files if you may need to downgrade. See the compatibility overview.

C++ and CMake integration

Rebuild downstream C++ code with matching headers and libraries; the C++ ABI remains under development. Check code that uses exposed Eigen types against Eigen 5.0.1.

rabitqlib::rabitqlib still supplies C++17, OpenMP, and required header definitions, but no longer propagates -O3 or -march=native. Set your application's optimization flags explicitly, including for inline library code. Sanitizer builds still propagate instrumentation and runtime linkage.

Local first-party builds enable native tuning by default. Set RABITQ_ENABLE_NATIVE_OPTIMIZATION=OFF for portable builds; release wheels use this setting and runtime dispatch.

Other changes

  • Thread-count detection accounts for Linux CPU affinity and supported OpenMP placement settings. Clustering reduces parallelism in short graph-building phases.
  • HNSW construction/insertion error handling and allocation-failure tests are improved.
  • Linux packages include GNU OpenMP license and exception texts.
  • Benchmark results and reproduction protocols are documented with their software versions.

Saving still writes directly to destination files. Applications manage backups and coordinate access to those files.