Defining a Vector Index by Annotation

In addition to providing a Vectorizer and VectorIndexConfiguration by hand (see Configuration), a vector similarity index can be declared with the @Vector annotation from the gigamap-jvector module.

Annotate the float[] field (or no-argument getter) that holds the entity’s embedding:

public class Product
{
    @Vector(dimension = 384, similarity = VectorSimilarityFunction.COSINE)
    private float[] embedding;
}
Attribute Meaning

name

Index name; defaults to the property name.

dimension

Required positive vector dimension; must match the length of the float[].

similarity

Similarity function (COSINE, EUCLIDEAN, DOT_PRODUCT); defaults to COSINE.

onDisk

Whether the index is stored on disk; requires a directory (see below). Defaults to false.

allowNull

Whether the annotated member may be null for some entities. When true, an entity with a null vector has no embedding: it stays in the GigaMap but is excluded from the vector index and never appears in search results. Defaults to false (a null vector throws). See Advanced Topics.

The vector is read from the entity when it is added or updated (embedded mode), and the index keeps a copy of it in its memory-mapped vector file, off the heap; plan disk space for that copy. An in-memory index uses a temporary vector file and re-reads every vector from the entities at each start; an on-disk index keeps the file in its index directory. See Where the Vectors Live.

Register the VectorAnnotationHandler with annotation-based generation and pass the GigaMap:

GigaMap<Product> gigaMap = GigaMap.New();
IndexerGenerator.AnnotationBased(Product.class)
    .register(VectorAnnotationHandler.New())
    .generateIndices(gigaMap);

gigaMap.add(new Product(/* ... embedding ... */));

VectorIndices<Product> vectors = gigaMap.index().get(VectorIndices.class);
VectorIndex<Product>   index   = vectors.get("embedding");
var results = index.search(queryVector, 10);

For on-disk indices (@Vector(onDisk = true)), create the handler with a base directory: VectorAnnotationHandler.New(baseDir); each index is stored in a sub-directory named after the index. Or create it with a named location, VectorAnnotationHandler.New(IndexLocation.Named("vectors")), bound to a directory at runtime; the index files are then kept directly in that directory. See Index Locations.

The handler is a no-op when the entity type carries no @Vector member, so it composes safely with bitmap (@Index) and other annotations on the same entity. See Annotation-based Indexing for the overall model.

Registering on a Populated Map

A vector index can also be added to a GigaMap that already holds entities — through generateIndices as above, or directly with VectorIndices.add or ensure. The new index is then back-filled from those entities.

The back-fill is the only step that runs your vectorizer over existing data, so it can fail when, for example, an embedding service times out. If the vectorizer throws, registration is all-or-nothing: the index is built before it becomes part of the map, so nothing is registered, the other indices remain untouched, and the next store() persists nothing from the attempt. Simply repeat the call; ensure then creates the index anew instead of returning a partially filled one.

With eventual indexing, the vectors of all existing entities are computed before registration, but the graph is built in the background afterwards, as for any later add. A vectorizer failure for an entity’s own vector is still reported by the call; failures while building the graph in the background are not — they are logged. The background build reads the vectors from the vector file and does not call the vectorizer.