Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions .agents/skills/graphile-search/references/pgvector-adapter.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
59 changes: 59 additions & 0 deletions graphile/graphile-search/src/__tests__/vector-unembedded.sql
Original file line number Diff line number Diff line change
@@ -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);
Loading
Loading