HNSW index returns only 1 result regardless of LIMIT on small tables (<100 rows)

[stuinfla]

Description

HNSW index scan returns only 1 result regardless of the LIMIT clause on tables with fewer than ~100 rows. Sequential scan on the same data returns the correct number of results.

Environment

• Extension: ruvector v0.1.0 (engine v2.0.1)
• Docker image: ruvnet/ruvector-postgres:latest (built 2026-02-13)
• Platform: macOS Darwin 25.3.0, Docker Desktop
• SIMD: x86_64 AVX2 + FMA + SSE4.2

Reproduction

-- Table: 56 rows, all with ruvector(384) embeddings
-- Column type: ruvector(384) (atttypmod correctly set)
-- Index: USING hnsw (embedding ruvector_cosine_ops) WITH (m=16, ef_construction=128)

-- WITH HNSW index: Returns 1 row (wrong)
SET ruvector.ef_search = 64;
SELECT title, category
FROM openclaw_memory.operational_knowledge
ORDER BY embedding <=> embed_text('What projects does Stuart work on?')
LIMIT 8;
-- Returns: 1 row

-- WITHOUT HNSW index (sequential scan): Returns 8 rows (correct)
DROP INDEX idx_opknowledge_embedding_hnsw;
SELECT title, category
FROM openclaw_memory.operational_knowledge
ORDER BY embedding <=> embed_text('What projects does Stuart work on?')
LIMIT 8;
-- Returns: 8 correct rows, properly ranked by relevance

Additional Context

• Tested with ruvector.ef_search values from 40 to 500 — no change
• Tested with precomputed vector in PL/pgSQL — same result
• All 56 embeddings confirmed as 384 dimensions via ruvector_dims()
• Column atttypmod is correctly set to 384 (not -1)
• Related: HNSW index causes errors on non-vector queries (COUNT, WHERE embedding IS NOT NULL) #152 (HNSW errors on non-vector queries), HNSW index scan segfault (signal 11) on tables >100K rows #164 (segfault on >100K rows)
• Workaround: Skip HNSW on tables with <1000 rows (sequential scan is sub-millisecond anyway)

[ruvnet]

Fix Applied in PR #172 (merged)

Root cause identified and fixed in commit b6988c9:

1. Hardcoded dimensions in hnsw_build (primary cause)

hnsw_am.rs:742 had let dimensions = 128; — a TODO that was never implemented. Your 384-dim embeddings were stored as 128-dim during index build, corrupting the graph structure.

Fix: Now extracts actual dimensions from column atttypmod:

let attr = (*tupdesc).attrs.as_ptr().offset((attnum - 1) as isize);
let typmod = (*attr).atttypmod;
// For ruvector(384), typmod == 384

2. Non-deterministic result ordering

BinaryHeap::into_iter() yields elements in arbitrary order (per Rust docs), not heap order. Combined with .take(k), this could miss nearest neighbors.

Fix: Replaced with into_sorted_vec() which guarantees ascending distance order:

let mut result_vec: Vec<_> = results
    .into_sorted_vec()  // deterministic nearest-first ordering
    .into_iter()
    .take(k)
    .map(|r| (r.block, r.tid, r.distance))
    .collect();

Action Required

After updating to ruvector-postgres 2.0.2, rebuild your HNSW indexes with REINDEX INDEX idx_opknowledge_embedding_hnsw; to regenerate the graph with correct 384 dimensions.

Version: ruvector-postgres 2.0.2 | PR: #172

[ruvnet]

Fixed in ruvector-postgres v2.0.2 (PR #172). Dimensions now read from column atttypmod. Please REINDEX after updating.