GVDB¶

A high-performance distributed vector database written in C++ for similarity search at scale.

Store, index, and search high-dimensional vectors — embeddings from OpenAI, Cohere, HuggingFace, and any other model — with sub-millisecond latency. Use GVDB to power semantic search, recommendation engines, RAG pipelines, image retrieval, and anomaly detection.

Why GVDB¶

• Vector search — FLAT, HNSW, IVF_FLAT, IVF_PQ, IVF_SQ, TurboQuant, IVF_TURBOQUANT index types with AUTO selection
• Sparse vectors — Inverted posting-list index for learned sparse retrieval (SPLADE, etc.)
• TurboQuant — Data-oblivious online quantization (ICLR 2026). ½/4/8-bit compression with near-optimal distortion; 7.5× at 4-bit on 768D
• Three-way hybrid search — Dense vectors + sparse vectors + BM25 text with Reciprocal Rank Fusion
• Per-vector TTL — Time-to-live with background sweep and query-time expiry filtering
• Distributed mode — Coordinator, data nodes, query nodes, proxy; full sharding and replication
• RBAC — Role-based access control with per-collection scoping and YAML config
• Tiered storage — Sealed segments uploaded to S3/MinIO; LRU local cache, lazy download
• GPU acceleration — Apple Metal kernels deliver 16–24× speedup over CPU on Apple Silicon
• Python SDK — Full API with hybrid search, streaming inserts, metadata, TTL, bulk import from Parquet/NumPy/pandas/h5ad

Architecture¶

graph TB
    Client([Client])

    subgraph Proxy Layer
        Proxy[gvdb-proxy<br/>Load Balancing]
    end

    subgraph Control Plane
        C1[gvdb-coordinator]
        C2[gvdb-coordinator]
        C3[gvdb-coordinator]
        C1 <--> C2
        C2 <--> C3
        C1 <--> C3
    end

    subgraph Data Plane
        DN1[gvdb-data-node<br/>Shards 1-4]
        DN2[gvdb-data-node<br/>Shards 5-8]
    end

    subgraph Query Plane
        QN1[gvdb-query-node]
        QN2[gvdb-query-node]
    end

    Client --> Proxy
    Proxy -- "metadata ops" --> C1
    Proxy -- "search" --> QN1 & QN2
    Proxy -- "insert/get/delete" --> DN1 & DN2
    QN1 & QN2 -- "ExecuteShardQuery" --> DN1 & DN2
    DN1 & DN2 -- "heartbeat" --> C1
    QN1 & QN2 -- "heartbeat" --> C1
    C1 -- "CreateSegment<br/>ReplicateSegment" --> DN1 & DN2

    style Proxy fill:#4a9eff,color:#fff
    style C1 fill:#ff6b6b,color:#fff
    style C2 fill:#ff6b6b,color:#fff
    style C3 fill:#ff6b6b,color:#fff
    style DN1 fill:#51cf66,color:#fff
    style DN2 fill:#51cf66,color:#fff
    style QN1 fill:#ffd43b,color:#333
    style QN2 fill:#ffd43b,color:#333

30-second quickstart¶

pip install gvdb

from gvdb import GVDBClient

client = GVDBClient("localhost:50051")
client.create_collection("vectors", dimension=768)
client.insert("vectors", ids=[1, 2], vectors=[[0.1]*768, [0.2]*768])

results = client.search("vectors", query_vector=[0.1]*768, top_k=10)
for r in results:
    print(r.id, r.distance)

helm install gvdb oci://ghcr.io/jonathanberhe/charts/gvdb \
  --namespace gvdb --create-namespace

kubectl port-forward -n gvdb svc/gvdb-proxy 50050:50050

docker run -p 50051:50051 \
  -v /tmp/gvdb:/var/lib/gvdb \
  ghcr.io/jonathanberhe/gvdb:latest \
  gvdb-single-node --port 50051 --data-dir /var/lib/gvdb

License¶

Apache License 2.0. GVDB is open source and free to use in commercial projects. See LICENSE.