qvcache-exploration

A workspace for exploring QVCache — a quantization-aware vector cache for ANN search — by running the reference C++ implementation and a Go port against a shared Weaviate backend on identical datasets and workloads.

Layout

Path	Kind	What it is
analysis/	tracked	Python harness (qvcompare) that drives both impls and produces reports
qvcache-go/	submodule	Go port — iangregson/qvcache-go
qvcache-vldb26/	submodule	Reference C++ impl from the VLDB '26 paper — iangregson/qvcache-vldb26 (fork of qvcache/qvcache-vldb26)
weaviate/	submodule	Weaviate backend used as the baseline — iangregson/weaviate (fork of weaviate/weaviate)
datasets/	gitignored	ANN benchmark inputs (sift-128, gist-960, glove-100-angular); fetched locally

Getting started

git clone --recurse-submodules <this-repo-url>
cd qvcache-exploration/analysis
# follow analysis/README.md from here

If you already cloned without submodules: git submodule update --init.

Fetch the datasets

The harness expects three ann-benchmarks HDF5 files under datasets/ at the workspace root:

mkdir -p datasets
cd datasets
curl -LO http://ann-benchmarks.com/sift-128-euclidean.hdf5
curl -LO http://ann-benchmarks.com/gist-960-euclidean.hdf5
curl -LO http://ann-benchmarks.com/glove-100-angular.hdf5

Expected layout:

datasets/
├── sift-128-euclidean.hdf5
├── gist-960-euclidean.hdf5
└── glove-100-angular.hdf5

uv run qvcompare prepare (from analysis/) converts these into the DiskANN binary format the runners consume; the converted files live under analysis/data/ and are also gitignored.

Run the comparison

The harness, prerequisites, and a quickstart for running the comparison matrix live in analysis/README.md. Headline results from the latest full run are in analysis/summary.md.