JVector Index
The JVector index adds vector similarity search capabilities to entities stored in a GigaMap. Like the Bitmap and Lucene indices, it is registered with the GigaMap and automatically kept in sync as entities are added, updated, or removed.
Under the hood, the index uses JVector, a high-performance HNSW (Hierarchical Navigable Small World) graph implementation. This enables fast approximate k-nearest-neighbor (k-NN) search on vector embeddings, making it ideal for AI/ML applications like semantic search, recommendation systems, and RAG (Retrieval-Augmented Generation).
What is Vector Search?
Traditional database queries find exact matches: "find all customers where city = 'Berlin'" or "find products where price < 100". Vector search is different - it finds similar items based on meaning or characteristics, even when there’s no exact match.
How it Works
-
Embeddings: Each entity (product, customer, document) is converted into a vector - an array of numbers that represents its characteristics. These vectors are typically generated by AI/ML models that understand the semantic meaning of text, images, or behavior patterns.
-
Similarity Search: Instead of matching exact values, vector search finds the entities whose vectors are closest to a query vector. "Closest" is determined by a similarity function (cosine, dot product, or euclidean distance).
-
Approximate Nearest Neighbors: For large datasets, exact similarity search is too slow. The JVector index uses an HNSW graph structure to find approximate nearest neighbors in milliseconds, even with millions of vectors.
When to Use Vector Search
| Query Type | Index Type | Example |
|---|---|---|
Exact match |
Bitmap |
|
Full-text search |
Lucene |
|
Similarity search |
JVector |
"Find products similar to this one" |
Use the JVector index when you need to:
-
Find similar products, customers, or content
-
Match questions to FAQ entries or support tickets
-
Search by meaning rather than keywords
-
Build recommendation systems
-
Implement semantic search with AI embeddings
Integration with GigaMap
The JVector index integrates seamlessly with GigaMap’s indexing system. When you add, update, or remove entities from the GigaMap, the vector index is automatically updated. Search results return lazy references to your entities, so you can access the full object without additional lookups.
You can combine vector search with bitmap indices for hybrid queries - for example, finding similar products within a specific category or price range.
Features
-
HNSW Vector Index: Fast approximate k-nearest-neighbor search using JVector’s HNSW graph implementation
-
Memory-Mapped Vector File: Vectors live in a memory-mapped file per index, a cache of what the vectorizer derives from the entities; the storage itself holds no vectors
-
On-Disk Index: Graph stored as immutable, memory-mapped segments committed by a manifest, for datasets larger than RAM; background merges keep the segment count low
-
PQ Compression: Product Quantization codes for traversing a graph larger than the page cache with fewer reads (trades disk or heap and some recall for I/O)
-
NVQ Storage: quantized vectors in the on-disk graph, about 3x smaller than full precision (scores stay exact; costs a little candidate recall only when
approximateScoringisNONE) -
Background Persistence: Automatic asynchronous persistence at configurable intervals
-
Background Optimization: Periodic graph cleanup of an in-memory index for improved query performance
-
Eventual Indexing: Deferred graph mutations via a background thread for reduced write latency
-
Lazy Entity Access: Search results provide direct access to entities without additional lookups
-
Stream API: Java Stream support for search results
Requirements
-
Java 25+. The module uses the foreign memory API for its vector file and is compiled for Java 25; the rest of EclipseStore stays at Java 17.
-
JVM flags:
-
--add-modules jdk.incubator.vectorfor SIMD scoring (without it, jVector falls back to scalar code). -
--enable-native-access=ALL-UNNAMEDfor jVector’s memory-mapped graph reader. On the module path jVector is the automatic modulejvector, so use--enable-native-access=jvectorthere.
-
SIMD Acceleration (Panama Vector API)
JVector leverages the Panama Vector API (jdk.incubator.vector) for hardware-accelerated vector operations. This provides significant performance improvements for ANN indexing and search through SIMD (Single Instruction, Multiple Data) instructions.
Benefits
-
Faster distance calculations: SIMD parallelizes vector arithmetic across CPU vector registers
-
Accelerated indexing: Graph construction benefits from parallel similarity computations
-
Faster queries: Nearest neighbor searches execute more quickly
-
Optimized PQ encoding: Product Quantization compression uses SIMD for distance computations
Enabling SIMD
| JVM flag | SIMD Support |
|---|---|
without |
Functional, but not optimized (scalar fallback) |
with |
Full SIMD acceleration via Panama Vector API |
JVector uses a multi-release JAR structure. On the Java 25+ JVM this module requires, the optimized vector code activates as soon as the incubator module is resolved.
JVM Parameters
To enable the Panama Vector API and jVector’s memory-mapped reader, add these flags to your JVM arguments:
java --add-modules jdk.incubator.vector --enable-native-access=ALL-UNNAMED -jar your-app.jar
See JVM Configuration for detailed setup instructions including Maven and Gradle configuration.
Always run with --add-modules jdk.incubator.vector. The performance difference can be substantial for large-scale vector operations.
|
Installation
<dependency>
<groupId>org.eclipse.store</groupId>
<artifactId>gigamap-jvector</artifactId>
<version>4.3.0</version>
</dependency>
Example
First, we need to implement a Vectorizer, which extracts the vector embedding from entities.
public class DocumentVectorizer extends Vectorizer<Document>
{
@Override
public float[] vectorize(Document entity)
{
return entity.embedding();
}
@Override
public boolean isEmbedded()
{
return true; // The vector is a field of the entity
}
}
Then we create a VectorIndex and register it at the GigaMap.
// Create GigaMap and register vector indices
GigaMap<Document> gigaMap = GigaMap.New();
VectorIndices<Document> vectorIndices = gigaMap.index().register(VectorIndices.Category());
// Configure the vector index
VectorIndexConfiguration config = VectorIndexConfiguration.builder()
.dimension(768)
.similarityFunction(VectorSimilarityFunction.COSINE)
.build();
// Add the index with a name, configuration, and vectorizer
VectorIndex<Document> index = vectorIndices.add("embeddings", config, new DocumentVectorizer());
After adding entities to the GigaMap, we can search for similar vectors.
// Add entities (automatically indexed)
gigaMap.add(new Document("Hello world", embedding));
// Search for similar vectors (returns top 10 results)
VectorSearchResult<Document> result = index.search(queryVector, 10);
for (ScoredSearchResult.Entry<Document> entry : result)
{
Document doc = entry.entity(); // Lazy entity access
float score = entry.score(); // Similarity score
long id = entry.entityId(); // Entity ID
}
The search results support the Java Stream API for convenient filtering and transformation.
List<Document> topDocs = result.stream()
.filter(e -> e.score() > 0.8f)
.map(ScoredSearchResult.Entry::entity)
.toList();
Tuning search effort per query
Every call uses a minimum beam width (HNSW efSearch) configured via minSearchBeamWidth (default 100). The effective beam width is max(k, minSearchBeamWidth) and keeps the top-k stable regardless of the requested k. A per-query overload lets you override this floor for a single call — useful to widen exploration for higher recall, or narrow it for lower latency when reproducibility across different k values is not required.
// Widen exploration for this query (higher recall, higher latency)
VectorSearchResult<Document> highRecall = index.search(queryVector, 10, 500);
// Narrow exploration for this query (lower latency, may differ from higher-k results)
VectorSearchResult<Document> fast = index.search(queryVector, 10, 10);
Similarity Functions
The following similarity functions are available:
| Function | Description |
|---|---|
|
Cosine similarity, normalized for direction. Best for text embeddings. |
|
Dot product similarity. Use when vectors are already normalized. |
|
Euclidean distance. Best for geometric or spatial data. |
Persistence with EclipseStore
Binary type handlers are registered automatically when using EclipseStore.
try (EmbeddedStorageManager storage = EmbeddedStorage.start(storageDir))
{
GigaMap<Document> gigaMap = GigaMap.New();
storage.setRoot(gigaMap);
VectorIndices<Document> vectorIndices = gigaMap.index().register(VectorIndices.Category());
VectorIndex<Document> index = vectorIndices.add("embeddings", config, new DocumentVectorizer());
gigaMap.add(new Document("text", embedding));
storage.storeRoot();
}
Shutting the storage down closes every index of the map; there is no need to close them explicitly.
Where the Vectors Live
The storage holds no vectors. Each index keeps its vectors in a memory-mapped vector file (<name>.vec plus chunks <name>.vec-<n>), a cache of what the Vectorizer derives from the entities. The entities are the source of truth, which has two consequences:
-
Vectorizer.vectorizemust reproduce the committed vector of a persisted entity. The index calls it again whenever it has to repair its vector file: after a crash for the entities written since the last checkpoint (seevectorCheckpointIntervalMs), and for every entity when the vector file is missing or does not match the stored index. -
Change what an entity’s vector derives from only through the GigaMap:
update/apply, orset/replacewith a new instance. A field mutated in place without them is not seen by the index, which keeps serving the old vector until a recovery orreindex()re-vectorizes the entity.
Where the vector file lives depends on the index:
-
An on-disk index keeps it in its index directory, next to its graph segments.
-
An in-memory index with a computed vectorizer (
isEmbedded()returnsfalse) keeps it in its index directory if one is configured (indexDirectoryorindexLocation), and then restarts without a vectorizer call per entity (VectorIndex.keepsIndexFiles()returnstrue). -
Every other in-memory index uses a temporary vector file and re-vectorizes every entity at each start. Temporary files live under
<java.io.tmpdir>/eclipsestore-vectors, or undereclipsestore-vectorsin the directory the system propertyorg.eclipse.store.gigamap.jvector.temporaryRootnames.
The vector file must stay with the storage it belongs to: back up and restore the index directory together with the storage. Deleting it only makes the next start re-vectorize every entity; restoring it separately from the storage is not supported.
Computed Vectorizers and Lazy Initialization
A vectorizer instance is part of the GigaMap’s persistent object graph: when storage is reopened, the vectorizer is restored alongside the index data and reused — its fields are loaded back exactly as they were when the GigaMap was last stored.
For computed vectorizers — those that derive embeddings on the fly, e.g. by calling an embedding model over HTTP — this means any heavy field on the vectorizer (HTTP clients, embedding-model handles, tokenizers) would otherwise be serialized along with the cheap configuration. Mark heavy fields transient and create them on first use; persist only the cheap configuration that identifies which model or endpoint to talk to.
public class MyVectorizer extends Vectorizer<Entity>
{
private final String baseUrl ;
private final String modelName;
private transient EmbeddingModel embeddingModel;
public MyVectorizer(final String baseUrl, final String modelName)
{
this.baseUrl = baseUrl ;
this.modelName = modelName;
}
private EmbeddingModel embeddingModel()
{
if(this.embeddingModel == null)
{
this.embeddingModel = OllamaEmbeddingModel.builder()
.baseUrl(this.baseUrl)
.modelName(this.modelName)
.build();
}
return this.embeddingModel;
}
@Override
public float[] vectorize(final Entity entity)
{
return this.embeddingModel().embed(toText(entity))
.content().vector();
}
}
When the GigaMap is loaded from existing storage, the vectorizer is restored from the persistent graph with its baseUrl and modelName intact. The transient embeddingModel field is null after deserialization and is recreated on the first vectorize call.
Since the index re-vectorizes entities to repair its vector file (see Where the Vectors Live), the model behind a computed vectorizer must stay deterministic: it must return the same vector for the same persisted entity. For an in-memory index backed by an embedding service, configure an indexDirectory or indexLocation, or every start calls the service once per entity, holding the GigaMap’s lock until it is done.
An expensive vectorizer can also override vectorKey(entity) to return a cheap version key of the entity’s vector (for example a record version). An update whose entity has the same key as the indexed one is taken to leave the vector unchanged, and vectorize is not called at all. The key must change whenever the vector changes; the default Vectorizer.NO_KEY compares vectors by content.
Looking up a vector index after load
The first argument to vectorIndices.add(name, configuration, vectorizer) is the index’s handle. GigaMap stores the index under that name and uses it as the filename prefix of the index files ({name}.vec, {name}.manifest, {name}.seg-{n}.graph, …) when the index keeps files in a directory, so pick a stable string that is also a valid filename. Avoid path separators and keep it short.
After the GigaMap is loaded from existing storage, the index is owned and managed by GigaMap — you do not re-add it. Retrieve a reference by name:
VectorIndices<Document> vectorIndices = gigaMap.index().get(VectorIndices.Category());
VectorIndex<Document> index = vectorIndices.get("embeddings");
vectorIndices.get(name) returns null if no index with that name is registered. If you want a single call site that creates the index on first run and reuses it on subsequent loads, use ensure(name, configuration, vectorizer) instead of add(…).
Limitations
-
Null vectors are rejected by default:
Vectorizer.vectorize()must not returnnullunless the vectorizer opts in viaVectorizer.allowsNullVectors(). By default anullvector throws anIllegalStateException. When opted in, anullvector means the entity has no embedding: it stays in the GigaMap but is excluded from the vector index and never appears in search results (see Advanced Topics). -
~2.1 billion vectors per index: JVector uses
intfor graph node ordinals. For larger datasets, implement sharding across multiple indices. -
Java 25 or later: the module targets Java 25 and uses the foreign memory API for its vector file.
-
The vector file must stay with its storage: it is a cache derived from the entities, rebuilt (one vectorizer call per entity) when it is missing or does not match the stored index.
-
FUSED_PQscoring enlarges the index: it stores each node’s neighbour codes inline, on top of whatever the storage mode holds. It saves reads on a graph larger than the page cache, not disk space, and it costs recall. To make the index smaller, setvectorStoragetoNVQ. -
NVQstorage never costs score accuracy: the graph keeps no full-precision copy, but reranking reads the full-precision vectors of the vector file, so the scores and the ordering a search returns are exact. WithapproximateScoring(NONE)it does change which candidates traversal finds, since traversal reads the quantized vectors; withFUSED_PQthe codes drive traversal and candidate selection is unchanged.
Upgrading from 4.x
The vectors of an index now live in the vector file instead of a persisted vector store, and the on-disk graph is a set of segments committed by a manifest instead of one <name>.graph/.meta/.pqv file set. A storage written by 4.0.0 to 4.2.0 opens without preparation:
-
A computed index imports the vectors of its old vector store into the vector file at its first use, without calling the vectorizer. An embedded index reads its vectors from the entities as before.
-
The next store of the map persists the index in the current layout; the old vector store becomes unreferenced and is reclaimed by the storage’s housekeeping.
-
The old graph files of an on-disk index are ignored, logged once at the first load, and can be removed. The graph is rebuilt from the vector file and persisted as segments beside them at the next persist, which is scheduled even if the index is only searched.
-
One way: a storage stored by this version cannot be opened by 4.x, or by an earlier build without the vector file, any more: they fail at start with
Missing runtime type … VectorIndexFormat(4.2.0 already atVectorStorage). Until the first store on this version, the storage still opens with the old version. Back up the storage before upgrading.
A 4.x in-memory index with a computed vectorizer and no directory imports its persisted vectors into a temporary vector file, which the current layout cannot keep. Storing the map is therefore refused until the index has a location: give it one with VectorIndices.changeIndexLocation (see Index Locations), which moves the imported vectors there at once, without a vectorizer call. To drop them deliberately instead, set the system property org.eclipse.store.gigamap.jvector.dropLegacyVectorsWithoutLocation=true; every later start then vectorizes every entity.
|