Skip to content
No Standalone Vector DB Needed: Embed Zvec in Java with a Single JAR

No Standalone Vector DB Needed: Embed Zvec in Java with a Single JAR

This tutorial demonstrates how to embed Alibaba's Zvec vector database directly into a Java application using a single JAR dependency, eliminating the need for a separate vector database service. It walks through vector search, Chinese full-text search with jieba, and hybrid retrieval using RRF fusion, while covering critical production considerations like data persistence, native memory management, and platform compatibility.

Java Architecture Diary
Java Architecture Diary
Java Architecture Diary

Embedded Vector Database in a Single JAR

PIG AI v6.4.2 replaced its default local vector storage VectoRex with Zvec, an open-source embedded vector database from Alibaba. Zvec runs entirely in-process — no external service, no remote IP, port, or authentication configuration. The engine loads when the Java process starts and persists data to a local directory on shutdown. It supports dense vectors, sparse vectors, and native BM25 full-text search (via jieba) within the same engine, removing the need for a separate Elasticsearch cluster or dual write logic.

Integration: One Maven Dependency

Add the following to pom.xml (version 0.8.0, requires Java 8+):

<dependency>
  <groupId>org.zvec</groupId>
  <artifactId>zvec-java</artifactId>
  <version>0.8.0</version>
</dependency>

Zvec's core is a C++ native engine. The published JAR bundles platform-specific dynamic libraries for common OS/arch combinations. At runtime, JavaCPP/JNI extracts and loads the appropriate native library. This introduces platform compatibility requirements — custom Linux images may need verification of dynamic library compatibility.

Hands-On Demo: Three Retrieval Modes with RRF Fusion

A self-contained ZvecHybridDemo shows three query types. The collection defines two fields: embedding — 3-dimensional VECTOR_FP32 field with Flat index and L2 (Euclidean) distance. content — STRING field with jieba tokenizer for full-text index (0.8.0 bundles the default jieba dictionary).

Two test documents are inserted to highlight complementary strengths:

Doc a: vector [1,0,0] (exact match to query vector), text "向量数据库支持混合检索" (keyword once).

Doc b: vector [0,1,0] (far from query), text "数据库数据库数据库" (keyword three times).

Note: Vectors are hand-crafted for observable ranking, not model-generated embeddings.

1. Vector-Only Search

try (VectorQuery query = new VectorQuery()) {
  query.setFieldName("embedding");
  query.setQueryVector(new float[]{1, 0, 0});
  query.setTopK(2);
  print("VECTOR", collection.query(query));
}

2. Full-Text-Only Search

try (VectorQuery query = new VectorQuery();
     FtsPayload fts = new FtsPayload()) {
  fts.setMatchString("数据库");
  query.setFieldName("content");
  query.setFts(fts);
  query.setTopK(2);
  print("FTS", collection.query(query));
}
VectorQuery

with setFts executes full-text search. Do not combine vector and full-text conditions in a single VectorQuery instance for single-route retrieval.

3. Hybrid Search with RRF Reranking

try (MultiQuery query = new MultiQuery();
     SubQuery vector = new SubQuery();
     SubQuery text = new SubQuery();
     FtsPayload fts = new FtsPayload()) {
  vector.setFieldName("embedding");
  vector.setQueryVector(new float[]{1, 0, 0});
  text.setFieldName("content");
  fts.setMatchString("数据库");
  text.setFts(fts);
  query.addSubQuery(vector);
  query.addSubQuery(text);
  query.setTopk(2);
  query.setRerankRrf(60);
  print("HYBRID", collection.query(query));
}

Two independent sub-queries (vector + text) are fused via Reciprocal Rank Fusion (RRF) with parameter k=60.

Observed Results (macOS ARM64, JDK 17)

VECTOR
 a 0.0
 b 2.0
FTS
 b 0.83709395
 a 0.5764419
HYBRID
 a 0.032522473
 b 0.032522473

VECTOR: L2 squared distance — smaller is closer. Doc a scores 0.0 (exact match), b scores 2.0.

FTS: BM25 score — higher is better. Doc b wins (0.837) due to three keyword occurrences; a scores 0.576.

HYBRID: RRF fusion yields identical scores (0.0325) for both docs, demonstrating balanced contribution from both routes.

Production Considerations

Fixed data path: The demo uses a temporary directory ( zvec-demo-<nanoTime>). Production must specify a fixed, reusable path so data survives process restarts.

Persistence: Call collection.flush() after writes to force data to disk.

Native memory release: Query results allocate off-heap memory. Always call Doc.freeDocs(results) in a finally block. Other resources (schema, collection, queries) are auto-closed via try-with-resources.

Engine lifecycle: Initialize once with Zvec.initialize(null) at startup; shut down with Zvec.shutdown() at exit.

Conclusion

Packing vector search, full-text search, and RRF hybrid reranking into a single JAR offers a lightweight option for Java developers who need semantic search on a single node or in local tools without operating a distributed vector database. The author recommends running a minimal demo with real data first to measure write latency, memory footprint, and recall before committing to Zvec in production.

Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

JavaRAGnative memoryjiebahybrid searchRRFZvecembedded vector database
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.