Skip to content

RaBitQ Library 0.8.5

This release prepares for 0.9: it adds the names that 0.9 will use and deprecates the 0.8 spellings they replace. Every 0.8 call keeps working, with the same results; index files and C++ are unchanged.

Python: names that change in 0.9

0.9 gives the three index classes one name for each concept (#232). This release accepts both spellings and raises a DeprecationWarning for the old one, at your call site. The migration guide lists each change.

  • HnswIndex.capacity replaces max_elements, and HnswIndex.reserve(num_points) replaces resize. reserve only grows the capacity.
  • max_elements is deprecated on IvfIndex and SymqgIndex; use num_stored_points.
  • IvfIndex.reserve_cluster(cluster_id, num_points) replaces reserve.
  • IvfIndex(routing=...) and index.routing replace initializer.
  • HnswIndex.search and SymqgIndex.search take ef_search= instead of ef=. Passing the breadth by position is unaffected.
  • Passing the search options after the breadth (high_accuracy, num_threads) by position is deprecated; 0.9 makes them keyword-only.
  • nprobe=0 and ef_search=0 for the default are deprecated; pass None or omit the argument. num_threads=0 keeps meaning every available CPU.
  • HnswIndex seeds above 2**32 - 1 are deprecated.

The k-means classes take the names of the index parameters (#233):

  • QGKMeans and QGKMeansParameters take nbits (32, 4 or 8), max_degree and ef_construction for quantization_bits (0, 4 or 8), graph_degree and ef_build.
  • final_assignment takes 'approximate' or 'exact', also as index.cp.final_assignment on IvfIndex and HnswIndex. FinalAssignmentMode members are still accepted, and the attribute still reads back as a member until 0.9.
  • KMeansIterationStats is the one name of the statistics class. QGKMeansIterationStats, RaBitQKMeansIterationStats and FinalAssignmentMode warn when imported or read from the package. The class now reports its name as KMeansIterationStats.

The type stubs mark the renamed 0.8 forms as deprecated, so mypy and Pyright can report them (mypy with --enable-error-code deprecated, Pyright with reportDeprecated). Three forms warn only at run time: nprobe=0 or ef_search=0, an HnswIndex seed above 2**32 - 1, and the two old names of KMeansIterationStats.

Python: other changes

  • IvfIndex.set_centroids takes num_threads (#231). Without it, set_centroids now follows OMP_NUM_THREADS, as train and add do; before, it always used every CPU. Only the HNSW routing graph varies with the thread count: build it with one thread and a fixed seed for a reproducible graph.

Coming in 0.9 without a warning

  • HnswIndex() without seed= will draw a seed, as IvfIndex and SymqgIndex do, instead of using 100. Pass seed=, and num_threads=1 to add, for a reproducible build.
  • repr(index) will print capacity= and routing= where it prints max_elements= and initializer=.
  • cp.final_assignment will read back as 'approximate' or 'exact' instead of a FinalAssignmentMode member.

Upgrading

From 0.8.4, index file formats, the stable core API v1 and C++ are unchanged, and every 0.8 Python call keeps its result. Code that uses a deprecated spelling now raises a DeprecationWarning; move to the new names with the migration guide before 0.9 removes the old ones. Rebuild C++ consumers with matching headers and libraries; no cross-version C++ binary ABI is promised.

When upgrading from 0.7, follow the 0.8.0 release notes and the migration guide.