HNSW index causes errors on non-vector queries (COUNT, WHERE embedding IS NOT NULL)

[stuinfla]

Bug Description

HNSW indexes on ruvector columns cause PostgreSQL errors on simple non-vector queries like COUNT(*) or WHERE embedding IS NOT NULL.

Steps to Reproduce

-- Create table with ruvector column
CREATE TABLE test (
  id SERIAL PRIMARY KEY,
  content TEXT,
  embedding ruvector(384)
);

-- Create HNSW index
CREATE INDEX idx_hnsw ON test 
USING hnsw (embedding ruvector_cosine_ops) WITH (m = 16, ef_construction = 100);

-- This query FAILS:
SELECT COUNT(*) FROM test WHERE embedding IS NOT NULL;

Error Message

ERROR: HNSW: Could not extract query vector from parameter. Ensure the query vector is properly cast to ruvector type, e.g.: ORDER BY embedding <=> '[1,2,3]'::ruvector(dim)
file: hnsw_am.rs, line: 1489

Expected Behavior

COUNT(*) and WHERE clauses on embedding columns should work regardless of HNSW index presence. The index should only be used for vector similarity searches (ORDER BY embedding <=> query).

Environment

• PostgreSQL 17.7
• ruvector-postgres Docker image (ruvnet/ruvector-postgres:latest)
• macOS via Docker Desktop

Workaround

Drop HNSW index and use brute-force scan. For <10K entries, brute-force is sub-100ms anyway.

Impact

Cannot use HNSW indexes in production because basic queries fail. This blocks using HNSW for performance optimization on larger datasets.

[fredrik-hansen]

Fix proposal for ruvector issue #152: HNSW/IVFFlat break non-vector queries

Problem

HNSW and IVFFlat index access methods intercept non-k-NN queries (COUNT(*), WHERE x IS NOT NULL, bitmap scans). Three bugs:

1. costestimate — reports low cost unconditionally → planner picks HNSW/IVFFlat for non-vector scans
2. rescan — calls pgrx::error!() when no query vector → crash instead of empty result
3. getbitmap (HNSW only) — logs warning! on every bitmap attempt → log spam

pgvector solves (1) by returning disable_cost when no ORDER BY operators exist.

Fix

crates/ruvector-postgres/src/index/hnsw_am.rs — 3 changes:

hnsw_costestimate — early return infinity when no ORDER BY:
if (*path).indexorderbys.is_null()
|| pg_sys::list_length((*path).indexorderbys) == 0
{
*index_startup_cost = f64::MAX;
*index_total_cost = f64::MAX;
*index_selectivity = 0.0;
*index_correlation = 0.0;
*index_pages = 0.0;
return;
}

hnsw_rescan — graceful empty instead of error!():
if !state.query_valid || state.query_vector.is_empty() {
pgrx::debug1!("HNSW: No query vector, returning empty result set");
state.results.clear();
state.search_done = true;
return;
}

hnsw_getbitmap — downgrade warning! → debug1!

crates/ruvector-postgres/src/index/ivfflat_am.rs — same costestimate + rescan fixes.

Even with these fixes, HNSW can SIGBUS on complex CTE + FULL OUTER JOIN patterns when the planner still picks it. Workaround: SET LOCAL enable_indexscan = off before such queries.
Root cause likely in the scan state management during joins — separate issue.

Thanks for being awesome, keep up the good work!

[ruvnet]

Fix Applied in PR #172 (merged)

Root cause: When PostgreSQL planned a non-kNN query (COUNT, WHERE IS NOT NULL) through the HNSW index, the hnsw_rescan callback always tried to extract a query vector from the ORDER BY operators. With norderbys == 0 (no ORDER BY), no vector was found, and line 1488 raised a hard error.

Fix

In hnsw_rescan: Early return when there are no ORDER BY operators:

// Non-kNN scan (e.g., COUNT(*), WHERE embedding IS NOT NULL)
if norderbys <= 0 || orderbys.is_null() {
    return;  // Let hnsw_gettuple handle gracefully
}

In hnsw_gettuple: Return false for non-kNN scans, forcing PostgreSQL to fall back to sequential scan:

if !state.query_valid && !state.search_done {
    return false;  // Force sequential scan fallback
}

After this fix, these queries work correctly with HNSW indexes present:

SELECT COUNT(*) FROM test WHERE embedding IS NOT NULL;  -- ✓ Works
SELECT * FROM test ORDER BY embedding <=> query LIMIT 5; -- ✓ Works (uses HNSW)

Version: ruvector-postgres 2.0.2 | PR: #172

[ruvnet]

Fixed in ruvector-postgres v2.0.2 (PR #172). Non-kNN queries now gracefully fall back to sequential scan.