jvector

JVector Release Notes

Version: 4.0.0-rc.9 - 4.0.1

New Features

Runtime Configuration for Graph Index Builder (JMX by default, pluggable backend)

PR: #703

Description
Introduces GraphIndexBuilderConfig, a managed singleton that exposes GraphIndexBuilder construction parameters as runtime-tunable attributes. Before this change, options such as addHierarchy, refineFinalGraph, and parallelBuild could only be set at the construction call site and required a code change or application restart to modify. With this change, all parameters — graph topology flags, write path selection, build-time compression type, and PQ compression tuning — can be inspected and updated live, without restarting the JVM.

Changes take effect the next time a GraphIndexBuilder is constructed; they do not affect indexes that are already being built or have already been built.

Architecture

GraphIndexBuilderConfig implements GraphIndexBuilderSettings, a plain domain interface with no dependency on JMX or any other transport, and registers itself with ManagementRegistry (package io.github.jbellis.jvector.management). The registry hands the registration to whichever ManagementBackend is active for the JVM. By default, that's JMX: the io.github.jbellis.jvector.management.jmx.JmxManagementBackend wraps GraphIndexBuilderConfig in a javax.management.StandardMBean and registers it with the platform MBeanServer under the object name io.github.jbellis.jvector:type=GraphIndexBuilderConfig — behaviorally identical to prior releases, so JConsole/jmxterm usage below is unchanged. All attributes are stored as volatile fields so writes from a management-backend thread are immediately visible to application threads without additional synchronization. Registration is best-effort throughout this stack: a failure (for example, in a restricted JVM environment) logs a warning but does not disrupt normal operation — the singleton continues to supply its default values.

The management backend is selectable per JVM via the jvector.management.backend system property:

See docs/admin-service-interfaces.md for the full design.

Managed Attributes

Graph topology

Write path

Build-time compression

PQ build compression parameters — consulted on

JVector Release Notes

Version: 4.0.0-RC.8 - 4.0.0-RC.9

New Features

Streaming N:1 Graph Index Compaction

PR: #659

Description
OnDiskGraphIndexCompactor merges multiple on-disk HNSW graph indexes into a single compacted index. This targets write-heavy workloads where data is continuously ingested into small segment indexes that accumulate over time; periodically compacting those segments into one larger index improves search throughput and recall without rebuilding from scratch.

Each source is an OnDiskGraphIndex paired with a FixedBitSet marking its live (non-deleted) nodes. The compactor merges all live nodes into a single graph, remaps each source's ordinals into a contiguous global ordinal space via user-supplied OrdinalMappers, and rebuilds each node's neighbor list using Vamana-style diversity selection over candidates gathered from the node's own source and from graph searches in the other sources. Sources are processed in parallel, batch-by-batch, with a bounded backpressure window so memory stays flat regardless of dataset size.

Purpose / Impact

• Consolidates many small segment indexes into one larger index, improving search throughput and recall without a full rebuild
• Excludes deleted nodes from the output, reclaiming space as part of the merge
• Bounded heap footprint — compaction streams per-source batches in parallel rather than materializing the full merged graph in memory. All benchmark datasets compact under -Xmx5g, including a 10M-vector, 2560-dimension dataset
• Measured recall is on par with or better than building a single index from scratch across a range of datasets

How to Enable
Construct an OnDiskGraphIndexCompactor from the source indexes, their live-node bitsets, and an ordinal remapper per source, then call compact():

List<OnDiskGraphIndex> sources = List.of(index0, index1, index2);

// Mark all nodes live (no deletions)
List<FixedBitSet> liveNodes = sources.stream()
    .map(s -> { var bs = new FixedBitSet(s.size()); bs.set(0, s.size()); return bs; })
    .collect(toList());

// Sequential ordinal remapping: source[s] node i -> global offset[s] + i
int offset = 0;
List<OrdinalMapper> remappers = new ArrayList<>();
for (var src : sources) {
    remappers.add(new OrdinalMapper.OffsetMapper(offset, src.size()));
    offset += src.size();
}

var compactor = new OnDiskGraphIndexCompactor(
    sources, liveNodes, remappers,
    VectorSimilarityFunction.COSINE,
    /* executor= */ null                  // null = use the core JVector thread pool
);

compactor.compact(Path.of("compacted.index"));

Deleted nodes are dropped by clearing their bit in the corresponding FixedBitSet and remapping only the surviving ordinals (for example with OrdinalMapper.MapMapper).

Notes

• The public compactor API is marked @Experimental and may change in a future release.
• Quantization is preserved across the merge. For FUSED_PQ sources the PQ codes are stored inline and the codebook is retrained on the combined dataset; non-fused sources can supply a sidecar CompressedVectors that is retrained and rewritten as a single merged file.
• PQ retraining uses balanced proportional sampling across all sources (up to ProductQuantization.MAX_PQ_TRAINING_SET_SIZE vectors total, at least 1000 per source).
• A new CompactorBenchmark (in benchmarks-jmh) measures compaction time, heap footprint, recall, and search latency. See docs/compaction.md for the full algorithm description and benchmarking instructions.

Performance Improvements

Fixes https://github.com/datastax/jvector/issues/629.

This pull request simplifies AVX-512 feature detection logic in the jvector_simd_check.c file by replacing manual CPUID bit checks with built-in compiler functions (available only on gcc and llvm compilers). The earlier code was missing X

Hotfix 1 for 4.0.0-rc.8

• Addresses destructive recall caused by usePruning by disabling it (Closes #678)

For the full release notes of the base release, see 4.0.0-rc.8.

JVector Release Notes

Version: 4.0.0-rc.7 - 4.0.0-rc.8

New Features and Enhancements

Fused Product Quantization (Fused PQ)

Description
Fused Product Quantization (Fused PQ) is a performance optimization that embeds compressed Product Quantization (PQ) codes directly into the graph index structure alongside each node's neighbor lists. This eliminates the need for separate lookups to retrieve compressed vectors during graph traversal, significantly improving query performance by reducing memory access overhead. The feature stores PQ-encoded neighbor vectors inline with the graph edges, enabling faster approximate similarity scoring during search operations. By embedding the compressed neighbor vectors into the graph index itself, Fused PQ eliminates the need to maintain a separate in-memory data structure for PQ-encoded vectors, reducing heap memory usage while maintaining fast approximate similarity search performance.​

Purpose / Impact

• Reduces memory usage for large-scale vector datasets
• Improves cache locality during graph traversal
• Enables higher writer scalability for large / high-dimensional vector workloads

How to Enable
To enable Fused PQ when writing an on-disk graph index:

1. Create the FusedPQ feature by passing your graph's max degree and a ProductQuantization compressor to the constructor:

   var fusedPQFeature = new FusedPQ(graph.maxDegree(), pq);
   

2. Add it to your OnDiskGraphIndexWriter builder:

   var writer = new OnDiskGraphIndexWriter.Builder(graph, outputPath)
       .with(fusedPQFeature)
       .build();
   

3. Provide a state supplier during the write phase that includes the graph view and PQ vectors:

   Map<FeatureId, IntFunction<Feature.State>> writeSuppliers = new EnumMap<>(FeatureId.class);
   writeSuppliers.put(FeatureId.FUSED_PQ, ordinal -> new FusedPQ.State(view, pqVectors, ordinal));
   writer.write(writeSuppliers);
   

Notes

• Fused PQ requires a 256-cluster ProductQuantization compressor. The feature automatically embeds compressed neighbor vectors inline with the graph structure during the write operation.
• To enable the FUSED_PQ feature, we introduced the new version 6 file format for our graph indices.

Parallel Graph Index Construction

Description
OnDiskParallelGraphIndexWriter significantly accelerates graph index construction by addressing the disk I/O bottleneck that limits the serial OnDiskGraphIndexWriter. This implementation uses asynchronous file I/O with multiple worker threads to write graph records in parallel, with parallelism automatically determined by available system resources (or configurable via builder options). By parallelizing both record building and disk writes while maintaining correct ordering, this approach dramatically reduces the time required to persist large graph indexes to disk.

Purpose / Impact

• Eliminates i/o bottleneck in on disk graph construction
• Maintains backwards compatibility for existing clients of the JVector library

How to Enable
To enable parallel graph index writes, simply use OnDiskParallelGraphIndexWriter.Builder instead of OnDiskGraphIndexWriter.Builder:

Basic usage (uses default parallelism based on available processors):

try (var writer = new OnDiskParallelGraphIndexWriter.Builder(graph, outputPath)
        .with(features...)
        .build()) {
    writer.write(featureSuppliers);
}

Advanced configuration:

try (var writer = new OnDiskParallelGraphIndexWriter.Builder(graph, outputPath)
        .with(features...)
        .withParallelWorkerThreads(8)           // Optional: specify thread count (0 = auto)
        .withParallelDirectBuffers(true)        // Optional: use direct ByteBuffers for better performance
        .build()) {
    writer.write(featureSuppliers);
}

The parallel wr