Cosine vectorSearch() defeats the embedding index it creates

Summary

The module creates a correct HNSW index for cosine collections (CREATE INDEX ... USING hnsw (embedding vector_cosine_ops), via vector_index_strategy), but the CosineSimilarity branch of PostgresPgvectorClient::vectorSearch() builds a query that cannot use that index. Every cosine similarity search falls back to a full sequential scan whose cost grows linearly with collection size and degrades badly under concurrency.

The generated query (cosine branch)

SELECT (1 - subquery.real_distance) AS distance, <fields>
FROM (
    SELECT embedding <=> '[...]' AS real_distance, <fields>
    FROM "collection" <filters>
) AS subquery
ORDER BY distance DESC
LIMIT k OFFSET n;

Why it cannot use the index

pgvector only uses an HNSW/IVFFlat index when the query is ORDER BY embedding <=> '[...]' ASC LIMIT k applied directly to the table. Here the distance is computed in a derived subquery, transformed to 1 - distance, and ordered DESC in the outer query. The planner does not rewrite (1 - d) DESC into d ASC, so the ANN index is invisible and Postgres does a Seq Scan + top-N sort over the entire collection — even though a matching vector_cosine_ops index exists.

Evidence

Collection: 295,317 rows, embedding vector(1024), cosine (<=>), with the module's HNSW index present.

Root cause

The cosine branch is special-cased to return a similarity (1 - distance) and sort DESC. That transformation hides the index. The EuclideanDistance and InnerProduct branches in the same method are already correct — they ORDER BY the raw operator ascending and are index-friendly.

Proposed fix (one clause)

Keep returning (1 - real_distance) AS distance for API compatibility, but order by the raw inner distance ascending. Ordering by the inner alias is sufficient (verified: it produces an Index Scan, identical result rows and identical returned similarity values).

// Before (lines ~507 and ~515)
... ) as {$alias} ORDER BY distance DESC LIMIT {$limit} OFFSET {$offset};

// After
... ) as {$alias} ORDER BY {$alias}.real_distance ASC LIMIT {$limit} OFFSET {$offset};

Related

Follow-up to #3576225, which added the HNSW/IVFFlat index strategy. That issue reported "HNSW and IVFFlat are faster than sequential scan," but did not verify via EXPLAIN that the cosine vectorSearch() query actually uses the index — which, per this report, it does not.

Steps to reproduce

1. Create a Postgres (pgvector) collection, set vector_index_strategy to HNSW, and index a non-trivial number of rows.
2. Run a cosine similarity search through the AI search stack.
3. Capture the SQL (Postgres log_min_duration_statement) and EXPLAIN ANALYZE it — observe Seq Scan despite the ..._embedding_idx HNSW index existing.
4. Change the ORDER BY as above and re-run — observe Index Scan.