VeloDB 🔥

In-Memory Vector Search Engine & key-Value Store

VeloDB is a high-performance, in-memory vector database built from scratch using Java (for the indexing graph and off-heap storage) and TypeScript (for the client SDK and benchmark suite). It provides sub-millisecond similarity search across high-dimensional vectors, optimized to run with zero JVM Garbage Collection pause overhead.

---

📖 VeloDB in Plain English (Layman's Terms)

When search engines recommend movies, search queries, or find visually similar images, they represent items as arrays of numbers called vectors (or embeddings). To find similar items, the system measures the "distance" between these coordinate lists.

Normally, finding similar vectors requires comparing your query to every single vector in the database, which is extremely slow.

VeloDB solves this using two advanced techniques:

1. Navigable Layered Graphs (HNSW): Instead of searching sequentially, VeloDB builds a multi-layered highway network (like a road map). It jumps across sparse highway nodes at top layers and only does local street-level searches at the bottom layers, cutting down search operations from thousands to logarithmic counts ($O(\log N)$).
2. GC-Free Native Memory: In Java, when you create millions of objects, the JVM Garbage Collector periodically pauses your server to clean up memory, causing latency spikes. VeloDB bypasses this by allocating memory directly in raw machine RAM outside the JVM Heap using direct memory buffers.
3. Hardware Acceleration (SIMD): It calculates vector math using CPU-level vector instructions. In a single clock cycle, the CPU performs multiple float operations concurrently (SIMD), accelerating distance loops.

---

📂 Project Structure

velodb/
├── client/                  <-- TypeScript client SDK & Benchmark suite
│   ├── src/
│   │   └── client.ts        <-- Binary float-array socket serializer & test client
│   ├── package.json
│   └── tsconfig.json
│
├── server/                  <-- High-performance vector database engine (Java)
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── com/
│   │               └── velodb/
│   │                   ├── VeloServer.java    <-- Binary TCP request parser
│   │                   ├── OffHeapMemory.java <-- sun.misc.Unsafe raw allocator
│   │                   ├── VectorMath.java    <-- SIMD CPU vector operations
│   │                   └── HNSWIndex.java     <-- Navigable layered graph
│   └── pom.xml              <-- Maven compilation properties (Java 17 targets)
│
├── package.json            <-- Monorepo workspaces coordinator
└── README.md               <-- You are here!

---

⚙️ Requirements

• Java JDK 17 (Ensure java and javac are in your PATH)
• Node.js (v20+ or Bun runtime)
• Git

---

🚀 How to Run the Benchmark

To compile, start the server, and run the test client benchmark, follow these steps:

1. Compile & Start the VeloDB Server (Terminal 1)

First, compile the server files with the experimental vector module flag enabled, and start the TCP listener:

cd server
mkdir -p target/classes
javac --add-modules jdk.incubator.vector -d target/classes src/main/java/com/velodb/*.java
java --add-modules jdk.incubator.vector -cp target/classes com.velodb.VeloServer

2. Run the Client Benchmark Suite (Terminal 2)

In another window, start the TypeScript client which inserts 1,000 vectors, queries nearest neighbors, and logs performance metrics:

cd client
npx tsx src/client.ts

📊 Expected Benchmark Output

When you run the client, you will see a detailed execution log showing:

• Batch Ingestions: Average insertion times per vector (usually less than 0.2ms).
• Search Latency: Round-trip query execution speed (usually sub-millisecond).
• Matches: A table showing closest coordinates (IDs) and exact Euclidean distance metrics!