At a glance

Measured on a laptop (Ryzen 7, 16 threads, WSL2) with the ANN-Benchmarks protocol. Full methodology, head-to-head tables and caveats: docs/BENCHMARKS.md.

Why Lattice

• Small RAM footprint, graph-class speed. Graph traversal is scored from 8-bit (SQ8) codes held in RAM; full-precision vectors and neighbor lists live in a compact, memory-mapped index file. In-RAM hnswlib is about 15–17% faster on one thread; Lattice delivers about 2.5× its throughput at 16 threads.
• Persistent and memory-mappable. The index is a single file. Open it with zero-copy mmap (the OS page cache becomes your RAM tier — more RAM, more cached) or via io_uring.
• Filtering that actually keeps recall. A filter-aware planner scans small match sets directly and widens the graph search for large ones — unfiltered-traversal-plus-post-filter collapses to recall 0.02–0.17 at 0.1–1% selectivity; this holds ≈ 1.0.
• Built on real-data evidence. Every claim here was measured on real datasets, not synthetic ones — and the real-data runs found bugs synthetic data hid (see docs/BENCHMARKS.md).

Python package

pip install lattice-vdb            # Linux x86_64, Python 3.10+
lattice fetch sift1m
lattice build ~/.lattice/data/sift-128-euclidean.hdf5 sift.lattice
lattice bench sift.lattice ~/.lattice/data/sift-128-euclidean.hdf5 ~/.lattice/data/sift-128-euclidean.hdf5 --ef 32,64,128

import lattice_vdb
lattice_vdb.build_index(vectors, "my.lattice", metric="cosine")   # l2, ip or cosine
index = lattice_vdb.Index("my.lattice", preload=True)
ids = index.search(query, k=10, ef_search=64)

lattice --help lists the commands: build, search, info, verify, bench, fetch.

Quick start (C++)

# Debian/Ubuntu prerequisites (system packages)
sudo apt install librocksdb-dev liburing-dev libroaring-dev

git clone <repo-url> && cd lattice
cmake --preset release && cmake --build build/release -j$(nproc)
ctest --test-dir build/release          # 108 tests
./build/release/examples/example_quickstart

Requires C++23 (GCC 15+ or Clang 17+) on Linux. On Windows, build under WSL2.

recall@5 vs brute force over 20 queries: 0.95
top-5 even ids for vector 123: 10540 16982 18722 7622 13252

Using the library

The complete, compiled version of this is examples/quickstart.cpp.

#include "lattice/quant/sq8.h"
#include "lattice/segment/segment.h"
using namespace lattice; using namespace lattice::index_graph;

// 1. Train the 8-bit codes that stay in RAM, choose a compact node layout, build the graph.
auto book   = quant::Sq8CodeBook::train(ptrs, dim);
quant::Sq8Codes codes(*book);
auto layout = NodeRecordLayout::make_compact(dim, ElemType::kFloat32, /*R=*/64);
VamanaBuildParams params;  params.r = 64;  params.build_list_size = 100;  params.metric = Metric::kL2;
auto built  = VamanaIndex::build(ptrs, dim, codes, params, *layout);   // multi-threaded by default

// 2. Save, then reopen disk-resident (zero-copy mmap; preload=true warms the cache in ~1 s).
built->serialize_to_disk("index.lattice");
auto index = segment::open_disk_resident_vamana("index.lattice", segment::NodeAccess::kMmap, /*preload=*/true);

// 3. Search. ef_search trades recall for speed (32 ≈ 0.975 recall@10, 192 ≈ 0.999 on SIFT1M).
SearchParams sp;  sp.ef_search = 64;
auto top10 = index->search(query, 10, sp);

// 4. Filtered search: pass the exact matching ids (sorted) and an admit callback.
VamanaIndex::FilteredParams fp;  fp.base = sp;  fp.matching_ids = matching_ids;
auto hits = index->search_filtered(query, 10, fp, [&](VectorId id) { return allowed(id); });

Metric::kL2 and Metric::kInnerProduct are supported (normalize vectors at ingest for inner product/cosine).

Performance

Real SIFT1M (1M × 128-d, all 10,000 queries, raw L2, k=10), one query at a time on a single thread unless noted. Warm page cache.

Against other systems on the same machine and protocol (single thread, QPS at matched recall@10):

At 16 threads Lattice reaches ~2× hnswlib's QPS at matched recall (17.5k vs 8.2k at ~0.99). Published figures (DiskANN, ANN-Benchmarks) come from different hardware and are mostly plots; they are quoted only as context in the benchmark doc.

How it works

flowchart LR
    Q([query]) --> S["Score neighbours from<br/>8-bit codes in RAM<br/>(~17 ns each, AVX2)"]
    S --> G["Greedy walk over a<br/>Vamana graph"]
    G --> N[("Compact node records<br/>mmap'd index file<br/>vector + neighbour ids")]
    N --> X["Exact fp32 distance<br/>for expanded nodes"]
    X --> K([top-k])

• Graph: Vamana (DiskANN-style) with α-relaxed pruning; the build is parallel (striped per-node locks).
• Codes: SQ8 per-dimension scalar quantization gates the traversal; the final ranking uses exact distances. (RaBitQ 1-bit codes are in the library but are not used for traversal — they were far less discriminative at 1M real vectors; see docs/BENCHMARKS.md.)
• Storage: one file of fixed-stride records (832 B at 128-d, R=64), served zero-copy through mmap; an io_uring backend is also available.
• Durability: write-ahead segment lifecycle, RocksDB-backed row store, two-phase durable seal; crash-injection tested over 10,000 points.

Filtered search

VamanaIndex::search_filtered plans per query:

• Few matches (≤ 150K): scan only the matching vectors from the in-RAM codes, then rerank exactly. Recall ≈ 1.0 regardless of how the filter correlates with the vectors.
• Many matches: graph traversal with the beam widened by 1/selectivity.

Recall@10, 1M vectors, exact filtered ground truth. Details in docs/BENCHMARKS.md.

Limitations

Being straight about what this is and isn't:

• A library, not a server. There is no network API, CLI, or Python package yet.
• 1M-vector scope. Larger scales (10M/100M) were deliberately dropped to ship a finished 1M system.
• Strongly clustered filters above ~15% selectivity use graph traversal and can lose recall (0.88–0.92 at 50%); scanning would restore it at ~45 ms p99.
• Warm-cache numbers. "Disk-resident" describes the layout and I/O path, not a cold-NVMe latency guarantee (see cold-start above).
• Not smaller than hnswlib when fully cached (~0.94 GB vs 0.65 GB); the benefit is that only 136 MB must stay resident and the rest degrades gracefully under memory pressure.
• Hard, unstructured data. On adversarial random 64-d Gaussian data the graph is weaker than hnswlib's (a vector finds itself 83% of the time at ef_search=64, vs 97% for hnswlib); on real SIFT1M recall@1 matches hnswlib. saturate_graph=true improves connectivity slightly; multi-entry-point or hierarchical search is the likely next step.
• Hybrid (lexical + vector) and multi-vector retrieval are planned, not built.
• Linux only (io_uring/mmap); on Windows use WSL2.

Project status

Documentation

cmake --preset release && cmake --build build/release -j$(nproc) && ctest --test-dir build/release

./build/release/bench/cpp/bench_production_sift1m <sift1m_bin_dir> <index_path> 10000 64 100
./build/release/bench/cpp/bench_filtered_sift1m   <sift1m_bin_dir> <index_path> 300

License

Lattice is licensed under the Apache License 2.0: you may use, modify and redistribute it, including commercially, provided you keep the license and NOTICE and state your changes. It includes an express patent grant and does not grant any right to use the project name or trademarks.

System dependencies (RocksDB, liburing, CRoaring) and the fetched GoogleTest keep their own licenses. Contributions are accepted under the same Apache-2.0 terms (section 5 of the license).