What is a thread-safety guarantee?
A thread-safety guarantee is an explicit statement of which concurrent operations on an HNSW index are safe to run together — for example “many searches at once,” “searches concurrent with inserts,” or “single writer only” — so callers know what the implementation promises and what remains undefined behavior.
Why does HNSW need a written concurrency contract instead of a vague “thread-safe” label?
The phrase “thread-safe” alone is almost meaningless for a graph index. Safe concurrent searches against a frozen graph are a different problem from safe concurrent inserts, which differ again from searches overlapping upserts and deletes. An implementation might allow parallel query serving with no writers, require external locking for all mutations, or document full read-mostly safety with internal per-node locks. Without a precise guarantee, users assume the strongest model, hit rare corruption under load, and blame “HNSW” rather than a mismatched contract. Good libraries state the allowed matrices of operations the way they state distance metrics and M defaults.
Those matrices usually fall into a few familiar tiers that match how production systems actually run.
What tiers of HNSW thread-safety guarantee are common?
The weakest useful tier is single-threaded access: one thread owns the index for both build and search. Next is concurrent read-only: many threads may search after construction completes, with no mutations — often safe with no locks if the graph is immutable. Stronger is concurrent search plus a single writer, or many writers with parallel insertion protocols. Strongest for serving is concurrent search and concurrent mutation under read-mostly graph safety. Each tier implies different internal machinery: nothing; immutable publication; global or per-node locks; epochs and atomics. In-memory databases such as Weaviate document which operations may overlap on an HNSW collection so operators do not invent an unsupported mix at the application layer.
A guarantee also clarifies what is intentionally not promised — especially about determinism and performance.
What should a thread-safety guarantee say it does not promise?
Concurrent inserts typically do not promise bit-identical graphs across runs; nondeterministic build order is expected. They do not promise that recall is identical to a single-threaded build, only that results remain well-defined and usually competitive when parameters are adequate. They do not promise wait-freedom or a latency bound under contention — only that the structure will not tear if you stay within the allowed operation set. Memory visibility rules (when a newly inserted vector becomes searchable to other threads) should be stated: immediate after insert returns, after a refresh, or after a generation bump. Leaving those unstated produces “missing document” bugs that look like search failures.
Callers must match their usage to the guarantee; exceeding it is a bug in the application, not a tuning issue.
How should you use an HNSW thread-safety guarantee when integrating or testing?
Read the documented concurrency model before enabling parallel query serving or multithreaded construction. If only concurrent reads are guaranteed, put a mutex around inserts or drain queries during rebuilds. If concurrent mutation is claimed, run stress tests that mix searches, inserts, and deletes under thread sanitizers and compare recall stability. Treat crashes or torn-looking neighbor lists under a supported mix as implementation bugs; treat the same under an unsupported mix as misuse. Prefer APIs that encode the contract — for example separate “build” and “searchable snapshot” objects — so the type system makes illegal concurrent use harder. A clear thread-safety guarantee is part of HNSW’s systems interface, equal in importance to the distance function.
A thread-safety guarantee spells out which concurrent HNSW operations are defined and safe, replacing a vague “thread-safe” claim with an explicit concurrency contract. From here, parallel query serving and parallel insertion are the operations being permitted or forbidden, read-mostly graph safety explains one strong tier, nondeterministic build order separates reproducibility from correctness, and the chapter on concurrent HNSW construction and querying shows how implementations earn those guarantees.