Insert and Search
Append vectors to a Basis instance and run k-nearest-neighbor queries.
What this page covers
The two operations a developer reaches for first: add to insert a vector under a UUID, and search to return the k nearest matches for a query vector.
HNSW is an approximate index. Recall depends on ef_search and graph topology — for high-precision workloads, retrieve a larger k and re-rank with an exact distance computation or a cross-encoder.
Construction
The direct constructor takes two Arc<RwLock<Strand>> handles. Use the SDK example for complete node setup and an in-process numeric-vector query. Basis::new starts an empty graph; it does not restore persisted records.
What add does
- Serializes
VectorEntry::Add { id, vector }withserde_json. - Appends the bytes to the vector strand. The Strand returns the new sequence number.
- Inserts the vector into the in-memory HNSW graph and records the internal index in a
DashMap<Uuid, usize>. - Calls
update_index_strand()(currently a no-op stub — see Snapshot and Recovery).
The add call is O(log N) on average for the HNSW insertion plus one Strand append.
What search does
- Builds a
Point { id: Uuid::nil(), vec: query }as the search probe. - Walks the HNSW graph with
ef = max(k, 24)to gather candidates. - Returns up to
k(Uuid, f32)pairs, sorted by ascending L2 distance.
| Parameter | Meaning |
|---|---|
query | Query vector. Must have the same dimensionality as inserted vectors. |
k | Maximum number of results. |
ef (internal) | Search width. Always ≥ 24 to keep recall stable on small k. |
Input and failure boundaries
Validate fixed dimensions and finite vector values before insertion or search. The distance function does not enforce these conditions and can panic on mismatched lengths. BasisError::Strand and BasisError::Serialization carry underlying failures; the declared VectorNotFound variant is not a guarantee that remove returns it for an absent id.
A failed or interrupted append is not documented as an atomic rollback. Inspect durable records before retrying. Present-id deletion can deadlock; see Snapshot and Recovery.
Memory sizing
The graph keeps copied f32 vectors plus HNSW, identifier-map and allocator overhead. 4 × dimensions × vector_count is only the raw vector-byte baseline, not a resident-memory measurement. Benchmark your actual workload; no tested fixed memory or recall figure is provided here.
