diff --git a/.agents/skills/graphile-search/references/pgvector-adapter.md b/.agents/skills/graphile-search/references/pgvector-adapter.md index bc9e40bcf0..e35ab95b4d 100644 --- a/.agents/skills/graphile-search/references/pgvector-adapter.md +++ b/.agents/skills/graphile-search/references/pgvector-adapter.md @@ -138,17 +138,28 @@ When `includeChunks` is active, the adapter generates: ```sql LEAST( - COALESCE(parent.embedding <=> $query, 'Infinity'::float), - COALESCE( - (SELECT MIN(c.embedding <=> $query) - FROM documents_chunks AS c - WHERE c.parent_id = parent.id), - 'Infinity'::float - ) + parent.embedding <=> $query, + (SELECT MIN(c.embedding <=> $query) + FROM documents_chunks AS c + WHERE c.parent_id = parent.id) ) ``` -`COALESCE` handles cases where the parent or chunks may not have embeddings. +`LEAST` ignores NULL operands, so this is the closest of the parent and its +chunks, and NULL only when neither has an embedding. The filter also adds + +```sql +parent.embedding IS NOT NULL +OR (SELECT MIN(c.embedding <=> $query) + FROM documents_chunks AS c + WHERE c.parent_id = parent.id) IS NOT NULL +``` + +to `WHERE`, so rows with no embedding anywhere are not returned, counted or +paged over. With `includeChunks: false` (and on tables without `@hasChunks`) +the predicate is just `parent.embedding IS NOT NULL`. The composite +`unifiedSearch` filter does not add this predicate: a row with no embedding can +still match through another adapter and simply has no vector score. ### GraphQL Query Examples diff --git a/graphile/graphile-search/src/__tests__/vector-unembedded.sql b/graphile/graphile-search/src/__tests__/vector-unembedded.sql new file mode 100644 index 0000000000..46dfeb4dea --- /dev/null +++ b/graphile/graphile-search/src/__tests__/vector-unembedded.sql @@ -0,0 +1,59 @@ +-- Seed for vector search over rows that have no embedding. +-- notes: parent embedding is nullable; notes_chunks: chunk embedding is nullable. +-- +-- Requires postgres-plus:18 image with: vector + +CREATE EXTENSION IF NOT EXISTS vector; + +CREATE SCHEMA IF NOT EXISTS vector_unembedded_test; + +CREATE TABLE vector_unembedded_test.notes ( + id serial PRIMARY KEY, + title text NOT NULL, + embedding vector(3) +); + +CREATE INDEX idx_notes_embedding ON vector_unembedded_test.notes + USING hnsw(embedding vector_cosine_ops); + +CREATE TABLE vector_unembedded_test.notes_chunks ( + id serial PRIMARY KEY, + note_id integer NOT NULL REFERENCES vector_unembedded_test.notes(id), + content text NOT NULL, + embedding vector(3) +); + +CREATE INDEX idx_notes_chunks_embedding ON vector_unembedded_test.notes_chunks + USING hnsw(embedding vector_cosine_ops); + +-- 7 rows: 3 with a parent embedding, 1 with a chunk embedding only, 3 with none. +INSERT INTO vector_unembedded_test.notes (id, title, embedding) VALUES + (1, 'parent embedding, no chunks', '[1, 0, 0]'), + (2, 'parent embedding, embedded chunk', '[0, 1, 0]'), + (3, 'no parent embedding, embedded chunk', NULL), + (4, 'no embedding anywhere', NULL), + (5, 'no parent embedding, unembedded chunk', NULL), + (6, 'parent embedding, no chunks (far)', '[0.707, 0.707, 0]'), + (7, 'no embedding anywhere (2)', NULL); + +SELECT setval('vector_unembedded_test.notes_id_seq', 7); + +INSERT INTO vector_unembedded_test.notes_chunks (id, note_id, content, embedding) VALUES + (1, 2, 'chunk close to [1,0,0]', '[0.9, 0.1, 0]'), + (2, 3, 'chunk along z', '[0, 0, 1]'), + (3, 5, 'chunk not yet embedded', NULL); + +SELECT setval('vector_unembedded_test.notes_chunks_id_seq', 3); + +-- memos: same rows as notes' parents, no chunks table and no vector index, +-- so the planner has to read every row (including the NULL ones). +CREATE TABLE vector_unembedded_test.memos ( + id serial PRIMARY KEY, + title text NOT NULL, + embedding vector(3) +); + +INSERT INTO vector_unembedded_test.memos (id, title, embedding) +SELECT id, title, embedding FROM vector_unembedded_test.notes; + +SELECT setval('vector_unembedded_test.memos_id_seq', 7); diff --git a/graphile/graphile-search/src/__tests__/vector-unembedded.test.ts b/graphile/graphile-search/src/__tests__/vector-unembedded.test.ts new file mode 100644 index 0000000000..72e3da6065 --- /dev/null +++ b/graphile/graphile-search/src/__tests__/vector-unembedded.test.ts @@ -0,0 +1,344 @@ +/** + * Vector search over rows that have no embedding. + * + * A row whose distance is NULL (no parent embedding and no embedded chunk) + * has nothing to rank, so vector search leaves it out — on the chunk-aware + * path and on the includeChunks:false path. Cursor paging then walks every + * scored row exactly once in both directions. + */ + +import type { GraphileConfig } from 'graphile-config'; +import { ConnectionFilterPreset } from 'graphile-connection-filter'; +import type { GraphQLResponse } from 'graphile-test'; +import { getConnections, seed } from 'graphile-test'; +import { join } from 'path'; +import type { PgTestClient } from 'pgsql-test'; + +import { createPgvectorAdapter } from '../adapters/pgvector'; +import { VectorCodecPlugin } from '../codecs/vector-codec'; +import { createUnifiedSearchPlugin } from '../plugin'; + +function makeTestSmartTagsPlugin( + tagsByTable: Record> +): GraphileConfig.Plugin { + return { + name: 'TestSmartTagsPlugin', + version: '1.0.0', + schema: { + hooks: { + init: { + before: ['UnifiedSearchPlugin'], + callback(_, build) { + for (const codec of Object.values(build.input.pgRegistry.pgCodecs)) { + const c = codec as any; + if (!c.attributes || !c.name) continue; + const tags = tagsByTable[c.name]; + if (!tags) continue; + if (!c.extensions) c.extensions = {}; + if (!c.extensions.tags) c.extensions.tags = {}; + Object.assign(c.extensions.tags, tags); + } + return _; + }, + }, + }, + }, + }; +} + +interface NoteNode { + rowId: number; + title: string; + embeddingVectorDistance: number | null; + searchScore: number | null; +} + +interface AllNotesResult { + allNotes: { + totalCount: number; + pageInfo: { hasNextPage: boolean; endCursor: string | null }; + nodes: NoteNode[]; + }; +} + +type QueryFn = ( + query: string, + variables?: Record +) => Promise>; + +const QUERY_VECTOR = '[1, 0, 0]'; +const CHUNK_AWARE = `vectorEmbedding: { vector: ${QUERY_VECTOR}, metric: COSINE }`; +const PARENT_ONLY = `vectorEmbedding: { vector: ${QUERY_VECTOR}, metric: COSINE, includeChunks: false }`; + +// Rows 1, 2 and 6 carry a parent embedding; row 3 only has an embedded chunk; +// rows 4, 5 and 7 have no embedding anywhere. +const CHUNK_AWARE_ROWS = [1, 2, 3, 6]; +const PARENT_ONLY_ROWS = [1, 2, 6]; + +describe('vector search excludes rows with no embedding', () => { + let db: PgTestClient; + let teardown: () => Promise; + let query: QueryFn; + + beforeAll(async () => { + const unifiedPlugin = createUnifiedSearchPlugin({ + adapters: [createPgvectorAdapter()], + enableSearchScore: true, + }); + + const smartTagsPlugin = makeTestSmartTagsPlugin({ + notes: { + hasChunks: { + chunksTable: 'notes_chunks', + parentFk: 'note_id', + parentPk: 'id', + embeddingField: 'embedding', + contentField: 'content', + }, + }, + }); + + const connections = await getConnections( + { + schemas: ['vector_unembedded_test'], + preset: { + extends: [ConnectionFilterPreset()], + plugins: [VectorCodecPlugin, smartTagsPlugin, unifiedPlugin], + }, + useRoot: true, + authRole: 'postgres', + }, + [seed.sqlfile([join(__dirname, './vector-unembedded.sql')])] + ); + + db = connections.db; + teardown = connections.teardown; + query = connections.query; + + await db.client.query('BEGIN'); + }); + + afterAll(async () => { + if (db) { + try { + await db.client.query('ROLLBACK'); + } catch { + // Ignore rollback errors + } + } + if (teardown) { + await teardown(); + } + }); + + beforeEach(async () => { + await db.beforeEach(); + }); + + afterEach(async () => { + await db.afterEach(); + }); + + async function fetchAll( + filter: string, + direction: 'ASC' | 'DESC', + connection: 'allNotes' | 'allMemos' = 'allNotes' + ): Promise { + const result = await query>(` + query { + ${connection}(where: { ${filter} }, orderBy: EMBEDDING_VECTOR_DISTANCE_${direction}) { + totalCount + nodes { rowId title embeddingVectorDistance searchScore } + } + } + `); + expect(result.errors).toBeUndefined(); + return result.data![connection].nodes; + } + + /** Walk every page with `first`/`after`, returning rowIds in page order. */ + async function pageThrough( + filter: string, + direction: 'ASC' | 'DESC', + first: number, + connection: 'allNotes' | 'allMemos' = 'allNotes' + ): Promise { + const seen: number[] = []; + let after: string | null = null; + for (let page = 0; page < 20; page++) { + const result: GraphQLResponse> = await query( + ` + query ($first: Int!, $after: Cursor) { + ${connection}( + first: $first + after: $after + where: { ${filter} } + orderBy: EMBEDDING_VECTOR_DISTANCE_${direction} + ) { + pageInfo { hasNextPage endCursor } + nodes { rowId title embeddingVectorDistance searchScore } + } + } + `, + { first, after } + ); + expect(result.errors).toBeUndefined(); + const conn = result.data![connection]; + seen.push(...conn.nodes.map((n) => n.rowId)); + if (!conn.pageInfo.hasNextPage) break; + after = conn.pageInfo.endCursor; + } + return seen; + } + + function sortedByDistance(nodes: NoteNode[], direction: 'ASC' | 'DESC'): number[] { + return [...nodes] + .sort((a, b) => + direction === 'ASC' + ? a.embeddingVectorDistance! - b.embeddingVectorDistance! + : b.embeddingVectorDistance! - a.embeddingVectorDistance! + ) + .map((n) => n.rowId); + } + + describe('chunk-aware path (includeChunks default)', () => { + it('returns only rows with a parent or chunk embedding, each with a finite distance', async () => { + const nodes = await fetchAll(CHUNK_AWARE, 'ASC'); + expect(nodes.map((n) => n.rowId).sort()).toEqual(CHUNK_AWARE_ROWS); + for (const node of nodes) { + expect(Number.isFinite(node.embeddingVectorDistance)).toBe(true); + } + // Row 3 is reached through its chunk [0,0,1] + const row3 = nodes.find((n) => n.rowId === 3)!; + expect(row3.embeddingVectorDistance).toBeCloseTo(1, 5); + }); + + it('reports totalCount over scored rows only', async () => { + const result = await query(` + query { allNotes(where: { ${CHUNK_AWARE} }) { totalCount nodes { rowId } } } + `); + expect(result.errors).toBeUndefined(); + expect(result.data!.allNotes.totalCount).toBe(CHUNK_AWARE_ROWS.length); + }); + + it.each([ + ['ASC', 1], + ['ASC', 2], + ['DESC', 1], + ['DESC', 2], + ] as Array<['ASC' | 'DESC', number]>)( + 'first/after paging (%s, first: %i) visits every scored row once, in order', + async (direction, first) => { + const all = await fetchAll(CHUNK_AWARE, direction); + const paged = await pageThrough(CHUNK_AWARE, direction, first); + expect(paged).toEqual(sortedByDistance(all, direction)); + expect([...paged].sort()).toEqual(CHUNK_AWARE_ROWS); + } + ); + + it('keeps the distance threshold', async () => { + const result = await query(` + query { + allNotes(where: { vectorEmbedding: { vector: ${QUERY_VECTOR}, metric: COSINE, distance: 0.5 } }) { + nodes { rowId embeddingVectorDistance } + } + } + `); + expect(result.errors).toBeUndefined(); + const nodes = result.data!.allNotes.nodes; + // Row 1 (parent [1,0,0]) and row 2 (chunk [0.9,0.1,0]) and row 6 ([0.707,0.707,0] → 0.29) + expect(nodes.map((n) => n.rowId).sort()).toEqual([1, 2, 6]); + for (const node of nodes) { + expect(node.embeddingVectorDistance).toBeLessThanOrEqual(0.5); + } + }); + }); + + describe('includeChunks: false path', () => { + it('returns only rows with a parent embedding', async () => { + const nodes = await fetchAll(PARENT_ONLY, 'ASC'); + expect(nodes.map((n) => n.rowId).sort()).toEqual(PARENT_ONLY_ROWS); + for (const node of nodes) { + expect(Number.isFinite(node.embeddingVectorDistance)).toBe(true); + } + }); + + it('reports totalCount over scored rows only', async () => { + const result = await query(` + query { allNotes(where: { ${PARENT_ONLY} }) { totalCount nodes { rowId } } } + `); + expect(result.errors).toBeUndefined(); + expect(result.data!.allNotes.totalCount).toBe(PARENT_ONLY_ROWS.length); + }); + + it.each([ + ['ASC', 1], + ['ASC', 2], + ['DESC', 1], + ['DESC', 2], + ] as Array<['ASC' | 'DESC', number]>)( + 'first/after paging (%s, first: %i) visits every scored row once, in order', + async (direction, first) => { + const all = await fetchAll(PARENT_ONLY, direction); + const paged = await pageThrough(PARENT_ONLY, direction, first); + expect(paged).toEqual(sortedByDistance(all, direction)); + expect([...paged].sort()).toEqual(PARENT_ONLY_ROWS); + } + ); + }); + + describe('table without a vector index or chunks (sequential scan)', () => { + const PLAIN = `vectorEmbedding: { vector: ${QUERY_VECTOR}, metric: COSINE }`; + + it('returns only rows with an embedding', async () => { + const nodes = await fetchAll(PLAIN, 'ASC', 'allMemos'); + expect(nodes.map((n) => n.rowId).sort()).toEqual(PARENT_ONLY_ROWS); + for (const node of nodes) { + expect(Number.isFinite(node.embeddingVectorDistance)).toBe(true); + } + }); + + it('reports totalCount over scored rows only', async () => { + const result = await query(` + query { allMemos(where: { ${PLAIN} }) { totalCount nodes { rowId } } } + `); + expect(result.errors).toBeUndefined(); + expect((result.data as any).allMemos.totalCount).toBe(PARENT_ONLY_ROWS.length); + }); + + it.each([ + ['ASC', 1], + ['ASC', 2], + ['DESC', 1], + ['DESC', 2], + ] as Array<['ASC' | 'DESC', number]>)( + 'first/after paging (%s, first: %i) visits every scored row once, in order', + async (direction, first) => { + const all = await fetchAll(PLAIN, direction, 'allMemos'); + const paged = await pageThrough(PLAIN, direction, first, 'allMemos'); + expect(paged).toEqual(sortedByDistance(all, direction)); + expect([...paged].sort()).toEqual(PARENT_ONLY_ROWS); + } + ); + }); + + describe('searchScore', () => { + it.each([ + ['chunk-aware', CHUNK_AWARE], + ['includeChunks: false', PARENT_ONLY], + ])('%s: every returned row has a distance and the closest row scores highest', async (_label, filter) => { + const nodes = await fetchAll(filter, 'ASC'); + for (const node of nodes) { + expect(node.embeddingVectorDistance).not.toBeNull(); + expect(node.searchScore).toBeGreaterThan(0); + expect(node.searchScore).toBeLessThanOrEqual(1); + } + // Sorted by distance ASC, so searchScore must be non-increasing + for (let i = 0; i < nodes.length - 1; i++) { + expect(nodes[i].searchScore!).toBeGreaterThanOrEqual(nodes[i + 1].searchScore!); + } + expect(nodes[0].rowId).toBe(1); + expect(nodes[0].searchScore).toBe(1); + }); + }); +}); diff --git a/graphile/graphile-search/src/adapters/pgvector.ts b/graphile/graphile-search/src/adapters/pgvector.ts index 038509bfab..6024797574 100644 --- a/graphile/graphile-search/src/adapters/pgvector.ts +++ b/graphile/graphile-search/src/adapters/pgvector.ts @@ -224,16 +224,17 @@ export function createPgvectorAdapter( WHERE ${chunksAlias}.${parentFk} = ${parentId} )`; - // Also compute direct parent distance if the parent has an embedding + // Direct parent distance (NULL when the parent has no embedding) const parentColumnExpr = sql`${alias}.${sql.identifier(column.attributeName)}`; const parentDistanceExpr = buildDistanceExpr(sql, parentColumnExpr, vectorExpr, resolvedMetric); - // Use LEAST of parent distance and closest chunk distance - // COALESCE handles cases where parent or chunks may not have embeddings - const combinedDistanceExpr = sql`LEAST( - COALESCE(${parentDistanceExpr}, 'Infinity'::float), - COALESCE(${chunkDistanceSubquery}, 'Infinity'::float) - )`; + // LEAST skips NULL operands, so this is the closest of parent + chunks + // and NULL only when neither the parent nor any chunk is embedded. + const combinedDistanceExpr = sql`LEAST(${parentDistanceExpr}, ${chunkDistanceSubquery})`; + + // Rows with no embedding anywhere have no distance to rank: leave them out. + // MIN(distance) is NULL exactly when no chunk has an embedding. + const scorableClause = sql`(${parentColumnExpr} IS NOT NULL OR ${chunkDistanceSubquery} IS NOT NULL)`; let whereClause: SQL | null = null; if (distance !== undefined && distance !== null) { @@ -243,6 +244,7 @@ export function createPgvectorAdapter( return { whereClause, scoreExpression: combinedDistanceExpr, + scorableClause, }; } @@ -258,6 +260,8 @@ export function createPgvectorAdapter( return { whereClause, scoreExpression: distanceExpr, + // A NULL embedding has no distance to rank: leave the row out. + scorableClause: sql`${columnExpr} IS NOT NULL`, }; }, }; diff --git a/graphile/graphile-search/src/plugin.ts b/graphile/graphile-search/src/plugin.ts index c67f796be3..b6c9881c92 100644 --- a/graphile/graphile-search/src/plugin.ts +++ b/graphile/graphile-search/src/plugin.ts @@ -816,7 +816,9 @@ export function createUnifiedSearchPlugin( const rankMetaKey = `${scoreMetaKey}__rank`; const orderDirection = adapter.scoreSemantics.lowerIsBetter ? 'ASC' : 'DESC'; - const rankSql = sql`(ROW_NUMBER() OVER (ORDER BY ${sql.parens(result.scoreExpression)} ${orderDirection === 'ASC' ? sql.fragment`ASC` : sql.fragment`DESC`} NULLS LAST))::text`; + // A row without a score has no rank: otherwise ROW_NUMBER() would + // hand unscored rows the positions right after the scored ones. + const rankSql = sql`(CASE WHEN ${sql.parens(result.scoreExpression)} IS NULL THEN NULL ELSE ROW_NUMBER() OVER (ORDER BY ${sql.parens(result.scoreExpression)} ${orderDirection === 'ASC' ? sql.fragment`ASC` : sql.fragment`DESC`} NULLS LAST) END)::text`; const rankIndex = qb.selectAndReturnIndex(rankSql); qb.setMeta(rankMetaKey, { selectIndex: rankIndex } as SearchScoreDetails); @@ -911,6 +913,10 @@ export function createUnifiedSearchPlugin( if (result.whereClause) { $condition.where(result.whereClause); } + // Only rows this adapter can score are returned + if (result.scorableClause) { + $condition.where(result.scorableClause); + } const qb = getQueryBuilder(build, $condition); injectScoreAndRank(qb, adapter, column, result, codec, $condition); diff --git a/graphile/graphile-search/src/types.ts b/graphile/graphile-search/src/types.ts index 87407ed0af..23d7ceabd6 100644 --- a/graphile/graphile-search/src/types.ts +++ b/graphile/graphile-search/src/types.ts @@ -56,6 +56,14 @@ export interface FilterApplyResult { whereClause: SQL | null; /** SQL expression that computes the score/distance/rank for this row */ scoreExpression: SQL; + /** + * Predicate that holds only for rows this adapter can score, e.g. + * `embedding IS NOT NULL` for pgvector. The adapter's own filter field ANDs + * it into WHERE so unscored rows are neither returned nor paged over. The + * composite `unifiedSearch` filter does not apply it: a row may still match + * through another adapter. + */ + scorableClause?: SQL | null; } /**