JVector Configuration
The VectorIndexConfiguration builder provides various options to tune the index for your specific use case.
JVM Configuration
The module requires Java 25 or later. Configure your JVM with the following parameters:
-
--add-modules jdk.incubator.vectorenables SIMD acceleration via the Panama Vector API. Without it, jVector falls back to scalar code. -
--enable-native-access=ALL-UNNAMEDallows jVector’s memory-mapped graph reader, which makes a restricted call on Java 22+. On the module path jVector is the automatic modulejvector, so name it there:--enable-native-access=jvector.
Required JVM Arguments
java --add-modules jdk.incubator.vector --enable-native-access=ALL-UNNAMED -jar your-app.jar
Full Example with Performance Tuning
java --add-modules jdk.incubator.vector \
--enable-native-access=ALL-UNNAMED \
-Djvector.physical_core_count=8 \
-jar your-app.jar
Maven Configuration
For Maven projects, configure the Surefire and Failsafe plugins:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<argLine>--add-modules jdk.incubator.vector --enable-native-access=ALL-UNNAMED</argLine>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<configuration>
<argLine>--add-modules jdk.incubator.vector --enable-native-access=ALL-UNNAMED</argLine>
</configuration>
</plugin>
Gradle Configuration
For Gradle projects:
tasks.withType<JavaExec> {
jvmArgs("--add-modules", "jdk.incubator.vector", "--enable-native-access=ALL-UNNAMED")
}
tasks.withType<Test> {
jvmArgs("--add-modules", "jdk.incubator.vector", "--enable-native-access=ALL-UNNAMED")
}
System Properties
Set with -D<property>=<value> on the JVM command line.
| Property | Default | Description |
|---|---|---|
|
Half of available processors |
Overrides the detected physical core count for parallel operations. Intensive SIMD operations can saturate memory bandwidth during indexing and PQ computation, so jVector’s |
|
|
The directory under which in-memory indices without an index directory create their temporary vector files, in its subdirectory |
|
|
Lets an in-memory index with a computed vectorizer and no index location, loaded from a 4.x storage, drop the vectors of its 4.x vector store at the next store; every later start then vectorizes every entity. Without it, storing such an index is refused until it has a location, see Upgrading from 4.x. |
The jdk.incubator.vector module is still an incubator module on Java 22 and later. JVector’s multi-release JAR handles the API differences automatically, but the module must still be explicitly enabled.
|
Basic HNSW Parameters
| Parameter | Default | Description |
|---|---|---|
|
(required) |
Vector dimensionality. Must match the size of your embedding vectors. |
|
|
Similarity metric ( |
|
16 |
Maximum connections per node in HNSW graph. Higher values improve recall but increase memory usage. With |
|
100 |
Beam width during index construction (HNSW efConstruction). Higher values improve graph quality but slow down construction. Has no effect at query time. |
|
100 |
Minimum beam width during search (HNSW efSearch floor). The effective beam width is |
|
1.2 |
How many candidate neighbours construction keeps before pruning, as a multiple of |
|
1.2 |
Aggressiveness of the RNG pruning heuristic during construction. |
On-Disk Storage
For datasets that exceed available memory, enable on-disk storage to use memory-mapped files. See On-Disk Index with Compression for an in-depth explanation of the segment and persist lifecycle, memory-mapped access, PQ compression theory, and the two-phase search with reranking.
| Parameter | Default | Description |
|---|---|---|
|
|
Store the graph as memory-mapped segment files instead of on the Java heap. This is what lets an index exceed available RAM: the OS pages the graph in and out, so heap stays flat and the cost moves to page cache and query latency. In-memory mode is faster per query but its graph is heap-resident, with the GC pressure that implies at scale, and it is rebuilt from the vector file at every start. |
|
|
Directory for the index files: segments, manifest and vector file. Required if |
|
|
Where the index files are, as an |
|
|
How the graph stores its own copy of each vector. |
|
|
How traversal scores candidates. Keep |
|
|
Number of NVQ subvectors (0 = auto: 1). Each subvector adds a fixed 28 bytes per node on top of the one byte per dimension, so the default is almost always right. Not the same parameter as |
|
|
Deprecated, use |
|
|
Number of PQ subspaces (0 = auto: dimension/4). Under |
|
|
Use parallel direct buffers and multiple worker threads for on-disk index writing. Speeds up persistence for large indices but uses more resources. Only applies when |
Example
VectorIndexConfiguration config = VectorIndexConfiguration.builder()
.dimension(768)
.similarityFunction(VectorSimilarityFunction.COSINE)
.onDisk(true)
.indexDirectory(Path.of("/data/vectors"))
.approximateScoring(ApproximateScoring.FUSED_PQ) // Only for a graph larger than the page cache
.pqSubspaces(48) // Must divide dimension evenly
.build();
On-Disk Format
An on-disk index is a set of immutable segments, committed by <name>.manifest:
-
<name>.seg-<n>.graph- the graph of segmentn; -
<name>.seg-<n>.l2g- the entity id of each node of segmentn; -
<name>.seg-<n>.pqv- the PQ codes of segmentn, only withPQ_IN_MEMORY.
The manifest records the state of the stored index it describes (vector count, highest entity id and a structural modification count) and carries a CRC32 checksum. A manifest that does not match the stored index, or a segment that fails to open, is rejected: the graph is rebuilt from the vector file and the next persist replaces the files. Graph files of 4.x (<name>.graph, .meta, .pqv) are ignored and logged once; they can be removed.
Segments and the Vector File
| Parameter | Default | Description |
|---|---|---|
|
|
Nodes the in-memory graph of an on-disk index must hold before a background persist writes it as a new segment. Keep it large: small segments add search cost without making anything more durable. An explicit |
|
|
How many segments of similar size a background merge combines into one (2-240). Larger merges less often and leaves more segments for every search to visit. Only relevant for on-disk indices. |
|
|
The most segments an on-disk index keeps (2-240). Background merges keep the count well below it; only if they fell behind does a persist consolidate all segments into one, blocking mutations and searches while it rebuilds. |
|
|
Interval at which the vector file is forced to disk and its chunks marked safe. After a crash only the chunks written since the last checkpoint are recovered, by re-vectorizing their entities. Shorter costs more header writes at runtime, longer more recovery after a crash. |
|
64 MB, or 2048 vectors where a large dimension needs more |
Size of one vector-file chunk; it must hold at least 2048 vectors. A chunk is written out in full when it is created, so a full disk fails as an exception, and it is the unit of recovery. Changing it for an existing index re-vectorizes every entity at the next start. |
The vector file (<name>.vec, chunks <name>.vec-<n>) is a cache of what the vectorizer derives from the entities, not a copy the storage commits: it must stay with the storage it belongs to. Deleting it only makes the next start re-vectorize every entity; restoring it separately from the storage is not supported. An index without a directory (every embedded in-memory index, and a computed one without indexDirectory/indexLocation) uses a temporary vector file and re-vectorizes every entity at each start. See Where the Vectors Live.
Eventual Indexing
Enable eventual indexing to defer expensive HNSW graph mutations to a background thread, reducing mutation latency at the cost of eventual search consistency.
| Parameter | Default | Description |
|---|---|---|
|
|
Defer HNSW graph mutations (add, update, remove) to a background thread. The vector file is updated synchronously, but graph construction happens asynchronously. Search results may not immediately reflect the most recent mutations. |
When enabled:
-
The vector file is always updated synchronously (no data loss).
-
HNSW graph mutations are queued and applied by a single background worker thread.
-
The queue is automatically drained before
optimize()andclose().persistToDisk()does not wait for it: it takes the pending operations into the graph it writes as a segment.
Parallel On-Disk Writes
When on-disk storage is enabled, persistence can optionally use parallel direct buffers and multiple worker threads (one per available processor) to write the index concurrently. This can significantly speed up persistence for large indices. See Parallel On-Disk Writes in the advanced section for more details.
This is disabled by default, as sequential single-threaded writing is preferred in resource-constrained environments or for smaller indices.
Background Persistence
Enable automatic asynchronous persistence of an on-disk index to avoid blocking operations during writes.
Setting persistenceIntervalMs to a value greater than 0 enables background persistence; it requires onDisk=true. A background persist writes the in-memory graph as a new segment once it holds flushThreshold nodes (see Segments and the Vector File). Persisting concerns the graph only: the vectors are in the vector file, which mutations write directly. See Production Configuration for a combined example.
| Parameter | Default | Description |
|---|---|---|
|
|
Check interval in milliseconds. A value > 0 enables background persistence, 0 disables it. |
|
|
Debounce threshold: the background thread persists only once this many changes have accumulated. Lower values keep the on-disk graph closer to the live state, at the cost of more write amplification; higher values mean a crash discards more work, which the load-time rebuild then has to redo. |
|
|
Persist pending changes on |
|
|
How long |
Example
VectorIndexConfiguration config = VectorIndexConfiguration.builder()
.dimension(768)
.similarityFunction(VectorSimilarityFunction.COSINE)
.onDisk(true)
.indexDirectory(Path.of("/data/vectors"))
.persistenceIntervalMs(30_000) // Enable, check every 30 seconds
.minChangesBetweenPersists(100) // Only persist if >= 100 changes
.persistOnShutdown(true) // Persist on close()
.build();
Background Optimization
Enable periodic graph optimization of an in-memory index to maintain query performance as the index grows.
Setting optimizationIntervalMs to a value greater than 0 enables background optimization. It has no effect on an on-disk index, which cleans up each graph as it writes it as a segment. See Manual Optimization and Persistence for manual control.
| Parameter | Default | Description |
|---|---|---|
|
|
Check interval in milliseconds. A value > 0 enables background optimization, 0 disables it. |
|
|
Debounce threshold for background optimization. Should be higher than |
|
|
Run a cleanup on pending changes during |
Example
VectorIndexConfiguration config = VectorIndexConfiguration.builder()
.dimension(768)
.similarityFunction(VectorSimilarityFunction.COSINE)
.optimizationIntervalMs(60_000) // Enable, check every 60 seconds
.minChangesBetweenOptimizations(1000) // Only optimize if >= 1000 changes
.optimizeOnShutdown(false) // Skip for faster shutdown
.build();
Parameter Guidelines
The following table provides recommended parameter values based on dataset size.
| Use Case | maxDegree | beamWidth | Notes |
|---|---|---|---|
Small dataset (<10K) |
8-16 |
50-100 |
Lower values sufficient |
Medium dataset (10K-1M) |
16-32 |
100-200 |
Balanced trade-off |
Large dataset (>1M) |
32-64 |
200-400 |
Higher for better recall |
High precision required |
48-64 |
400-500 |
Maximum recall |