Skip to content

fix(graphile-search): exclude rows with no embedding from vector search - #1978

Merged
devin-ai-integration[bot] merged 2 commits into
mainfrom
feat/vector-search-exclude-unembedded
Nov 9, 2026
Merged

devin-ai-integration[bot] merged 2 commits into
mainfrom
feat/vector-search-exclude-unembedded

Conversation

@pyramation

@pyramation pyramation commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Summary

A row whose parent embedding is NULL and whose chunks (if any) all have NULL embeddings has no distance to rank. The pgvector adapter used to keep such rows anyway: the chunk-aware path scored them LEAST(COALESCE(d, 'Infinity'), COALESCE(chunk_d, 'Infinity')), which GraphQL's Float serializer rejects (Float cannot represent non numeric value: Infinity), and the parent-only path scored them NULL, so totalCount counted them and first/after paging over a NULL cursor lost rows depending on the plan (HNSW index scan skips NULLs; a seq scan does not). They now stay out of the result set on both paths.

Mechanics:

  • SearchAdapter.applyFilter result gains an optional scorableClause: SQL. The pgvector adapter sets it to embedding IS NOT NULL (parent-only / no @hasChunks) or embedding IS NOT NULL OR (SELECT MIN(chunk_d) FROM chunks c WHERE c.fk = parent.pk) IS NOT NULL (chunk-aware; same subquery as the distance expression, and MIN is NULL exactly when no chunk is embedded). The plugin ANDs it into the per-adapter filter's WHERE next to whereClause. The composite unifiedSearch filter does not apply it: a row with no embedding can still match via another adapter.
  • Chunk-aware distance is now LEAST(parent_d, (SELECT MIN(chunk_d) ...)) with no COALESCE(..., 'Infinity'). LEAST ignores NULL operands, and the predicate above means the only rows where both are NULL are gone.
  • searchScore rank: ROW_NUMBER() OVER (ORDER BY score NULLS LAST) became CASE WHEN score IS NULL THEN NULL ELSE ROW_NUMBER() ... END, so rows an adapter cannot score contribute no rank to the RRF fusion instead of being numbered right after the scored rows. The existing score field descriptions ("Returns null when no ... search filter is active") are still accurate and are unchanged.
  • .agents/skills/graphile-search/references/pgvector-adapter.md updated to the new SQL.

Not in this PR (noted only): deep paging past the default hnsw.ef_search limit (hnsw.iterative_scan), and the underlying @dataplan/pg behaviour where a NULL ORDER BY value yields a cursor that drops rows.

Tests

New src/__tests__/vector-unembedded.test.ts + vector-unembedded.sql: nullable vector(3) columns with HNSW indexes on a parent + chunks table, plus the same rows in a table with no index (forces a seq scan). Covers chunk-aware and includeChunks: false row sets, totalCount, first/after paging in both directions, the distance threshold, and searchScore monotonicity.

  • On main: 14 failed / 7 passed (Infinity serialization errors, totalCount 7 instead of 3/4, seq-scan paging returning unembedded rows).
  • On this branch: 21 passed. Full package: 5 suites / 96 tests pass. tsc --noEmit clean; eslint src reports only the pre-existing unused scoreMetaKey warning.

HNSW plan, 200k rows (64-dim, 10% NULL parents, 50k chunks of which 10k NULL), ORDER BY distance LIMIT 10, PG 18, warm cache, 3 runs

path before after
parent-only (includeChunks: false) Index Scan docs_embedding_idx, 0.28–0.31 ms Index Scan docs_embedding_idx + Filter: (embedding IS NOT NULL), 0.11–0.12 ms
chunk-aware Seq Scan + top-N heapsort, 348–373 ms Seq Scan (Rows Removed by Filter: 20000) + top-N heapsort, 337–340 ms

The parent-only path keeps the HNSW index scan; the NULL predicate is applied as a filter on top of it. The chunk-aware path never used the index (ordering by LEAST(...) over a subquery is not indexable) and is unchanged in shape. An EXISTS (... embedding IS NOT NULL) form of the chunk predicate was also measured (386–389 ms, planner hashes it into a full chunks scan) and rejected in favour of reusing the MIN subquery.

Link to Devin session: https://app.devin.ai/sessions/2c8a6e5b1ad0423f8bb10849a019c44b
Open in Devin Desktop: https://app.devin.ai/desktop/session/2c8a6e5b1ad0423f8bb10849a019c44b?variant=devin
Requested by: @pyramation

Rows whose parent embedding and every chunk embedding are NULL have no
distance to rank. The pgvector adapter now reports a scorable predicate
(embedding IS NOT NULL, or an embedded chunk exists on the chunk-aware
path) that the filter ANDs into WHERE, and the chunk-aware distance is a
plain LEAST(parent, chunk) instead of COALESCE(..., 'Infinity'). This
stops Infinity reaching the GraphQL Float serializer, makes totalCount
and first/after paging consistent on both paths, and keeps the HNSW
index scan for parent-only ordering. The rank window used by
searchScore is NULL for unscored rows instead of numbering them after
the scored ones.
@devin-ai-integration

Copy link
Copy Markdown
Contributor

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

  • Disable automatic comment, CI, and merge conflict monitoring

@luxor-code-review

luxor-code-review Bot commented Nov 9, 2026 •

Copy link
Copy Markdown

Review complete. 🟡 1 medium

💬 Inline comments (1)


The PR makes vector search exclude rows that cannot be scored instead of passing Infinity distances through COALESCE, and stops assigning numeric ranks to unscored rows so they no longer participate in rank-based paging or scoring aggregates. A new scorableClause is threaded from the pgvector adapter through the plugin's filter application so unembeddable rows are dropped from vector search results, covered by a dedicated fixture and integration test asserting exclusion, totalCount, paging, and searchScore behavior, plus a reference-doc update for the pgvector adapter.

Files Change
graphile/graphile-search/src/adapters/pgvector.ts Replaces COALESCE(…, 'Infinity') with NULL-skipping LEAST for combined distance and emits the new scorableClause predicate.
graphile/graphile-search/src/plugin.ts Applies scorableClause in the adapter's filter apply and CASE-wraps rank/score so unscored rows yield NULL.
graphile/graphile-search/src/types.ts Adds the optional scorableClause field to FilterApplyResult.
graphile/graphile-search/src/__tests__/vector-unembedded.sql New seed fixture with a mix of embedded and unembedded rows for the exclusion scenarios.
graphile/graphile-search/src/__tests__/vector-unembedded.test.ts New integration test covering exclusion, totalCount, paging, and searchScore.
.agents/skills/graphile-search/references/pgvector-adapter.md Documents the new unembedded-row exclusion semantics.

Reviewed commit: 76782b3

@luxor-code-review luxor-code-review Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR fixes NULL-embedding handling in the graphile-search pgvector adapter by switching the combined parent/chunk distance to a NULL-skipping LEAST, adding a scorableClause exclusion predicate to FilterApplyResult, and making the rank NULL for unscored rows, with a new seed fixture and integration test.

Key findings

Comment on lines +236 to +241
const scorableClause = sql`(${parentColumnExpr} IS NOT NULL OR EXISTS (
SELECT 1
FROM ${chunksTableRef} AS ${chunksAlias}
WHERE ${chunksAlias}.${parentFk} = ${parentId}
AND ${chunksAlias}.${chunkEmbedding} IS NOT NULL
))`;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 performance · medium

Duplicate correlated chunk EXISTS added per row

The new scorableClause at pgvector.ts:236-241 adds a second correlated EXISTS (SELECT 1 FROM chunks WHERE parent_fk = ... AND embedding IS NOT NULL) evaluated for every candidate row in the WHERE clause, even though the adjacent chunkDistanceSubquery (lines 221-225) already scans the same chunks rows to compute MIN(distance). Postgres does not common-subquery-eliminate these, so chunk-table scanning work per parent row roughly doubles on the vector search path, worst for parents with many chunks.

📋 Prompt for AI Agents

In graphile/graphile-search/src/adapters/pgvector.ts around lines 235-241, remove the newly added EXISTS (SELECT 1 FROM chunks ...) used as scorableClause. Reuse the existing chunkDistanceSubquery variable (lines 221-225) and express the scorable predicate as (${parentColumnExpr} IS NOT NULL OR ${chunkDistanceSubquery} IS NOT NULL), avoiding a second scan of the chunks table per candidate row.

@devin-ai-integration
devin-ai-integration Bot merged commit 994c652 into main Nov 9, 2026
19 checks passed
@devin-ai-integration
devin-ai-integration Bot deleted the feat/vector-search-exclude-unembedded branch November 9, 2026 03:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant