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.vector enables SIMD acceleration via the Panama Vector API. Without it, jVector falls back to scalar code.

  • --enable-native-access=ALL-UNNAMED allows jVector’s memory-mapped graph reader, which makes a restricted call on Java 22+. On the module path jVector is the automatic module jvector, 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

jvector.physical_core_count

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 PhysicalCoreExecutor limits concurrency to physical cores rather than logical cores (hyperthreads). A property of the jVector library.

org.eclipse.store.gigamap.jvector.temporaryRoot

java.io.tmpdir

The directory under which in-memory indices without an index directory create their temporary vector files, in its subdirectory eclipsestore-vectors. Only that subdirectory is written and cleaned up.

org.eclipse.store.gigamap.jvector.dropLegacyVectorsWithoutLocation

false

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

dimension

(required)

Vector dimensionality. Must match the size of your embedding vectors.

similarityFunction

COSINE

Similarity metric (COSINE, DOT_PRODUCT, EUCLIDEAN).

maxDegree

16

Maximum connections per node in HNSW graph. Higher values improve recall but increase memory usage. With approximateScoring=FUSED_PQ, this also multiplies the per-node fused block (pqSubspaces * maxDegree bytes), so it drives both the graph size and the bytes read per traversal hop.

beamWidth

100

Beam width during index construction (HNSW efConstruction). Higher values improve graph quality but slow down construction. Has no effect at query time.

minSearchBeamWidth

100

Minimum beam width during search (HNSW efSearch floor). The effective beam width is max(k, minSearchBeamWidth). Keeps the top-k stable across different k values; set to 1 to disable the floor and make the beam width equal to the requested k. Independent of beamWidth. Can be overridden per query via search(query, k, searchBeamWidth).

neighborOverflow

1.2

How many candidate neighbours construction keeps before pruning, as a multiple of maxDegree. Higher values select neighbours slightly better at the cost of more memory while building. Minimal effect on final quality or query speed - the default suits almost everything.

alpha

1.2

Aggressiveness of the RNG pruning heuristic during construction. 1.0 keeps every Voronoi neighbour; higher values drop edges reachable by other paths, giving a sparser graph and faster queries at the cost of some recall. Raise it only under memory pressure.

Example

VectorIndexConfiguration config = VectorIndexConfiguration.builder()
    .dimension(768)
    .similarityFunction(VectorSimilarityFunction.COSINE)
    .maxDegree(32)
    .beamWidth(200)
    .build();

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

onDisk

false

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.

indexDirectory

null

Directory for the index files: segments, manifest and vector file. Required if onDisk=true, unless indexLocation is set. An in-memory index with a computed vectorizer keeps its vector file there too, and then restarts without a vectorizer call per entity; see Where the Vectors Live.

indexLocation

null

Where the index files are, as an IndexLocation: Absolute(path) is the same as indexDirectory(path); Named(name) stores only a name, bound to a directory at runtime, so a moved or restored storage can be pointed at its index files. See Index Locations.

vectorStorage

INLINE

How the graph stores its own copy of each vector. INLINE keeps full precision (dimension * 4 bytes per node). NVQ stores 8-bit quantized vectors (4 + dimension + 28 * nvqSubvectors bytes per node), which is about 3x smaller, and is the only setting that makes the graph file smaller. Reranking is exact under both, but reads from different places: an inline graph carrying fused codes reranks from its own mapping, while an NVQ graph has no full-precision copy and reads the vector file. With approximateScoring=NONE traversal reads the quantized vectors and so finds slightly different candidates; with FUSED_PQ the codes drive traversal and candidate selection is unchanged. Requires onDisk=true.

approximateScoring

NONE

How traversal scores candidates. Keep NONE while the graph fits in the page cache: scoring from PQ codes saves reads, not arithmetic, so there it is slower and finds fewer of the true nearest neighbours. FUSED_PQ writes Product Quantization codes into every node, so traversing a graph larger than the page cache reads one block per hop, at the cost of a larger graph file and some recall; it requires onDisk=true. PQ_IN_MEMORY buys the same approximate traversal without touching the graph, keeping the codes in heap - pqSubspaces bytes per ordinal, resident, against pqSubspaces * maxDegree bytes per node on disk. An on-disk index persists them in a .pqv file per segment, read back on load; an in-memory index has no persist and therefore no such file, building them during optimization instead. It is also the only PQ-based mode available to an in-memory index - NONE remains the default there - and it requires optimizationIntervalMs > 0: the switch from exact to compressed scoring is a rebuild, and optimization is where it happens. A scheduled optimization is necessary but not sufficient: the background manager skips one until minChangesBetweenOptimizations changes have accumulated, and that defaults to 1000. An index that settles between the 256 vectors PQ training needs and that threshold stays on exact scoring until something calls optimize() explicitly, and build() warns when the two are configured that way.

nvqSubvectors

0

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 pqSubspaces, whose auto value would make an NVQ block larger than the vector it replaces. Only applies when vectorStorage=NVQ.

enablePqCompression

false

Deprecated, use approximateScoring instead. A literal delegate: true means FUSED_PQ, false means NONE.

pqSubspaces

0

Number of PQ subspaces (0 = auto: dimension/4). Under FUSED_PQ this costs pqSubspaces * maxDegree bytes per node on disk, so prefer a smaller value than classic PQ guidance suggests; under PQ_IN_MEMORY it is pqSubspaces bytes per ordinal in heap. Only applies when approximateScoring is one of those two.

parallelOnDiskWrite

false

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 onDisk=true.

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 segment n;

  • <name>.seg-<n>.l2g - the entity id of each node of segment n;

  • <name>.seg-<n>.pqv - the PQ codes of segment n, only with PQ_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

flushThreshold

100000

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 persistToDisk() and the shutdown persist write regardless. Only relevant for on-disk indices.

segmentMergeFactor

4

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.

maxSegments

32

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.

vectorCheckpointIntervalMs

30000

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.

vectorChunkBytes

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

eventualIndexing

false

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() and close(). persistToDisk() does not wait for it: it takes the pending operations into the graph it writes as a segment.

Example

VectorIndexConfiguration config = VectorIndexConfiguration.builder()
    .dimension(768)
    .similarityFunction(VectorSimilarityFunction.COSINE)
    .eventualIndexing(true)
    .build();

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.

Example

VectorIndexConfiguration config = VectorIndexConfiguration.builder()
    .dimension(768)
    .similarityFunction(VectorSimilarityFunction.COSINE)
    .onDisk(true)
    .indexDirectory(Path.of("/data/vectors"))
    .parallelOnDiskWrite(true)
    .build();

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

persistenceIntervalMs

0

Check interval in milliseconds. A value > 0 enables background persistence, 0 disables it.

minChangesBetweenPersists

100

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. 0 or 1 persists on every interval.

persistOnShutdown

true

Persist pending changes on close() when onDisk=true. Applies whether or not background persistence is enabled.

shutdownPersistTimeoutMillis

30000

How long close() waits for the final drain, optimize and persist before interrupting it and continuing. An aborted persist loses no data - the vectors are in the vector file, and the manifest is committed atomically - it only costs a graph rebuild from the vector file on the next start. The shutdown persist writes the in-memory graph as one more segment and never rebuilds, so this mainly bounds the write of a large in-memory graph or an unexpectedly slow drain.

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

optimizationIntervalMs

0

Check interval in milliseconds. A value > 0 enables background optimization, 0 disables it.

minChangesBetweenOptimizations

1000

Debounce threshold for background optimization. Should be higher than minChangesBetweenPersists, since a cleanup is the more expensive of the two. 0 or 1 optimizes on every interval.

optimizeOnShutdown

false

Run a cleanup on pending changes during close(). Disabled by default because it blocks shutdown; leaving it off trades a slower first query after restart for a faster exit.

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