docs: add chunk-aware search (@hasChunks) to graphile-search skill

pyramation · pyramation · commit be963e714c96 · 2026-03-20T00:07:01.000Z
- pgvector-adapter.md: new 'Chunk-Aware Search' section with @hasChunks config, includeChunks field, generated SQL, and GraphQL examples
- codegen-sdk-queries.md: ORM examples for chunk-aware search, opt-out, and distance threshold with chunks
- SKILL.md: mention chunk-aware RAG in architecture overview, SDK query patterns, and common pitfalls
diff --git a/skills/graphile-search/SKILL.md b/skills/graphile-search/SKILL.md
@@ -32,9 +32,11 @@ UnifiedSearchPlugin
   ├── TsvectorAdapter     (keyword search with stemming)
   ├── Bm25Adapter         (relevance-ranked document search)
   ├── TrgmAdapter         (fuzzy matching, typo tolerance)
-  └── PgvectorAdapter     (semantic/embedding similarity)
+  └── PgvectorAdapter     (semantic/embedding similarity + chunk-aware RAG)
 ```
 
+The pgvector adapter also supports **chunk-aware search** via the `@hasChunks` smart tag — transparently querying across parent and chunk embeddings and returning the minimum distance. See `references/pgvector-adapter.md` for details.
+
 Each adapter implements the `SearchAdapter` interface:
 - **`detectColumns()`** — finds searchable columns on a table (e.g. tsvector columns, columns with BM25 indexes)
 - **`registerTypes()`** — registers any custom GraphQL types (e.g. filter input types)
@@ -219,6 +221,7 @@ After running `cnc codegen`, the generated SDK client exposes search filters, sc
 - **BM25 queries** — `bm25Content`, `bm25ContentScore` (negative, sort ASC)
 - **Trigram queries** — `similarTo`/`wordSimilarTo` via `StringTrgmFilter`, adapter-level `trgmTitle`, ILIKE
 - **pgvector queries** — `vectorEmbedding`, `embeddingDistance`, distance metrics (COSINE/L2/IP)
+- **Chunk-aware search** — `includeChunks` toggle for RAG tables with `@hasChunks`, transparent parent + chunk distance
 - **Multi-strategy patterns** — fuzzy fallback, autocomplete pipeline, semantic + keyword hybrid
 
 ## Score Semantics
@@ -241,6 +244,7 @@ Bounded ranges use linear normalization. Unbounded ranges use sigmoid normalizat
 | No search fields on table | No search infrastructure detected | Add tsvector column, BM25 index, or vector column |
 | trgm operators missing | Table has no intentional search | Add tsvector/BM25, or use `@trgmSearch` smart tag |
 | `searchScore` is null | No search filters active in query | Add a search filter (fullTextSearch, bm25Body, etc.) |
+| `includeChunks` field missing | No `@hasChunks` tables in schema | Add `@hasChunks` smart tag to parent table codec |
 | `Unknown type "FullText"` | TsvectorCodecPlugin not loaded | Use `UnifiedSearchPreset()` which includes all codecs |
 | `Unknown type "Vector"` | VectorCodecPlugin not loaded | Use `UnifiedSearchPreset()` which includes all codecs |
 | Duplicate type errors | Multiple search presets | Use only `UnifiedSearchPreset()`, not individual presets |
diff --git a/skills/graphile-search/references/codegen-sdk-queries.md b/skills/graphile-search/references/codegen-sdk-queries.md
@@ -401,10 +401,93 @@ const result = await db.document.findMany({
 | `content_vec` | `vectorContentVec` | `contentVecDistance` | `CONTENT_VEC_DISTANCE_ASC/DESC` |
 
 **Pattern:**
-- Filter: `vector` + CamelCase(column) — accepts `{ vector: [Float!]!, metric?: String, distance?: Float }`
+- Filter: `vector` + CamelCase(column) — accepts `{ vector: [Float!]!, metric?: String, distance?: Float, includeChunks?: Boolean }`
 - Distance: camelCase(column) + `Distance` (Float, lower = closer, null when no filter active)
 - OrderBy: SCREAMING_SNAKE(column) + `_DISTANCE_ASC/DESC`
 
+### Chunk-Aware Vector Search
+
+Tables with the `@hasChunks` smart tag automatically get chunk-aware search. The distance returned is `LEAST(parent_distance, MIN(chunk_distance))` — the best match across the document embedding and all chunk embeddings.
+
+Chunk search is **on by default** for `@hasChunks` tables. No extra code is needed:
+
+```typescript
+// Chunk-aware search — ON by default for @hasChunks tables
+// Distance = LEAST(parent embedding distance, closest chunk distance)
+const result = await db.document.findMany({
+  where: {
+    vectorEmbedding: {
+      vector: queryVector,
+      metric: 'COSINE',
+      // includeChunks defaults to true when @hasChunks is present
+    },
+  },
+  orderBy: 'EMBEDDING_DISTANCE_ASC',
+  first: 10,
+  select: {
+    id: true,
+    title: true,
+    embeddingDistance: true,   // best distance across parent + all chunks
+  },
+}).execute();
+
+if (result.ok) {
+  result.data.documents.nodes.forEach(d => {
+    console.log(`${d.title} (distance: ${d.embeddingDistance})`);
+  });
+}
+```
+
+### Opt Out of Chunk Search
+
+Set `includeChunks: false` to only search the parent embedding:
+
+```typescript
+const result = await db.document.findMany({
+  where: {
+    vectorEmbedding: {
+      vector: queryVector,
+      metric: 'COSINE',
+      includeChunks: false,    // only use parent embedding
+    },
+  },
+  orderBy: 'EMBEDDING_DISTANCE_ASC',
+  first: 10,
+  select: {
+    id: true,
+    title: true,
+    embeddingDistance: true,   // parent distance only
+  },
+}).execute();
+```
+
+### Chunk-Aware Search with Distance Threshold
+
+The distance threshold applies to the combined (chunk-aware) distance:
+
+```typescript
+const result = await db.document.findMany({
+  where: {
+    vectorEmbedding: {
+      vector: queryVector,
+      metric: 'COSINE',
+      distance: 0.3,           // threshold applies to LEAST(parent, chunk)
+    },
+    isPublished: { equalTo: true },
+  },
+  orderBy: 'EMBEDDING_DISTANCE_ASC',
+  first: 20,
+  select: {
+    id: true,
+    title: true,
+    embeddingDistance: true,
+    searchScore: true,         // composite 0..1 relevance
+  },
+}).execute();
+```
+
+> **Note:** `includeChunks` only appears on `VectorNearbyInput` when at least one table in the schema has the `@hasChunks` smart tag. For tables without chunks, the field is absent and vector search behaves as standard parent-only search.
+
 ---
 
 ## Multi-Strategy Patterns
diff --git a/skills/graphile-search/references/pgvector-adapter.md b/skills/graphile-search/references/pgvector-adapter.md
@@ -82,6 +82,102 @@ enum DocumentsOrderBy {
 
 pgvector is the only primary adapter that sets `isIntentionalSearch: false`. This is because vector embeddings operate on a different domain than text search — a table with only pgvector columns shouldn't get trgm similarity fields on its text columns.
 
+## Chunk-Aware Search (`@hasChunks`)
+
+Tables with long-form content (documents, articles, etc.) often split text into **chunks**, each with its own embedding. The pgvector adapter transparently queries across parent and chunk embeddings when the `@hasChunks` smart tag is present on the table's codec.
+
+### How It Works
+
+1. The parent table has a `vector(N)` column (the document-level embedding)
+2. A separate chunks table stores per-chunk embeddings with a foreign key back to the parent
+3. The `@hasChunks` smart tag tells the adapter where to find the chunks table
+4. At query time, the adapter computes `LEAST(parent_distance, MIN(chunk_distance))` — the best match across all embeddings
+
+### Smart Tag Configuration
+
+Set `@hasChunks` on the parent table codec as a JSON object:
+
+```json
+{
+  "chunksTable": "documents_chunks",
+  "parentFk": "parent_id",
+  "parentPk": "id",
+  "embeddingField": "embedding"
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `chunksTable` | *(required)* | Name of the chunks table |
+| `chunksSchema` | parent table's schema | Schema of the chunks table |
+| `parentFk` | `parent_id` | Column in chunks table that references the parent |
+| `parentPk` | `id` | Primary key column on the parent table |
+| `embeddingField` | `embedding` | Vector column in the chunks table |
+
+In Constructive, the `DataEmbedding` node type with chunks enabled automatically creates the chunks table and wires up the relationship. The smart tag is applied via a Graphile plugin or smart tags file.
+
+### `includeChunks` Filter Field
+
+When `@hasChunks` is detected, `VectorNearbyInput` gains an `includeChunks` boolean field:
+
+```graphql
+input VectorNearbyInput {
+  vector: [Float!]!
+  metric: VectorMetric
+  distance: Float
+  includeChunks: Boolean   # only present when @hasChunks is on the table
+}
+```
+
+- **`true` (default for `@hasChunks` tables):** Distance = `LEAST(parent_distance, MIN(chunk_distance))`
+- **`false`:** Distance = parent embedding distance only
+
+### Generated SQL
+
+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
+  )
+)
+```
+
+`COALESCE` handles cases where the parent or chunks may not have embeddings.
+
+### GraphQL Query Examples
+
+```graphql
+# Chunk-aware (default) — returns best distance across parent + all chunks
+query {
+  allDocuments(where: {
+    vectorEmbedding: { vector: [0.1, 0.2, ...], metric: COSINE }
+  }) {
+    nodes {
+      title
+      embeddingVectorDistance   # LEAST(parent, closest chunk)
+    }
+  }
+}
+
+# Parent-only — opt out of chunk search
+query {
+  allDocuments(where: {
+    vectorEmbedding: { vector: [0.1, 0.2, ...], metric: COSINE, includeChunks: false }
+  }) {
+    nodes {
+      title
+      embeddingVectorDistance   # parent distance only
+    }
+  }
+}
+```
+
 ## VectorCodecPlugin
 
 The `VectorCodecPlugin` (included in `UnifiedSearchPreset`) teaches PostGraphile about the `vector` PostgreSQL type:
