graphile-search 1.12.0 → 1.13.0

package/adapters/bm25.d.ts

@@ -6,6 +6,11 @@
  *
  * Requires the Bm25CodecPlugin to be loaded first (for index discovery).
  * The adapter reads from the bm25IndexStore populated during the gather phase.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a BM25 index, the adapter includes a lateral
+ * subquery to find the best-matching chunk and returns
+ * LEAST(parent_score, chunk_score) (lower = better for BM25).
  */
 import type { SearchAdapter } from '../types';
 /**

package/adapters/bm25.js

@@ -7,10 +7,16 @@
  *
  * Requires the Bm25CodecPlugin to be loaded first (for index discovery).
  * The adapter reads from the bm25IndexStore populated during the gather phase.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a BM25 index, the adapter includes a lateral
+ * subquery to find the best-matching chunk and returns
+ * LEAST(parent_score, chunk_score) (lower = better for BM25).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBm25Adapter = createBm25Adapter;
 const bm25_codec_1 = require("../codecs/bm25-codec");
+const chunks_1 = require("./chunks");
 function isTextCodec(codec) {
     const name = codec?.name;
     return name === 'text' || name === 'varchar' || name === 'bpchar';
@@ -62,7 +68,14 @@ function createBm25Adapter(options = {}) {
                 const bm25Index = getBm25IndexForAttribute(codec, attributeName, build);
                 if (!bm25Index)
                     continue;
-                columns.push({ attributeName, adapterData: bm25Index });
+                // Check for chunk-aware BM25
+                const chunksInfo = (0, chunks_1.getChunksInfo)(codec);
+                const hasChunkBm25 = chunksInfo?.searchIndexes.includes('bm25');
+                const columnData = {
+                    bm25Index,
+                    chunksInfo: hasChunkBm25 ? chunksInfo : undefined,
+                };
+                columns.push({ attributeName, adapterData: columnData });
             }
             return columns;
         },
@@ -97,15 +110,53 @@ function createBm25Adapter(options = {}) {
         buildFilterApply(sql, alias, column, filterValue, _build) {
             if (filterValue == null)
                 return null;
-            const { query, threshold } = filterValue;
+            const { query, threshold, includeChunks } = filterValue;
             if (!query || typeof query !== 'string' || query.trim().length === 0)
                 return null;
-            const bm25Index = column.adapterData;
+            const columnData = column.adapterData;
+            const bm25Index = columnData.bm25Index;
             const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
             // Use quoteQualifiedIdentifier to produce the qualified index name
             const qualifiedIndexName = `"${bm25Index.schemaName}"."${bm25Index.indexName}"`;
             const bm25queryExpr = sql `to_bm25query(${sql.value(query)}, ${sql.value(qualifiedIndexName)})`;
             const scoreExpr = sql `(${columnExpr} <@> ${bm25queryExpr})`;
+            // Check for chunk-aware querying
+            const chunksInfo = columnData.chunksInfo;
+            if (chunksInfo && chunksInfo.searchIndexes.includes('bm25') && (includeChunks !== false)) {
+                const chunksTableRef = chunksInfo.chunksSchema
+                    ? sql `${sql.identifier(chunksInfo.chunksSchema)}.${sql.identifier(chunksInfo.chunksTableName)}`
+                    : sql `${sql.identifier(chunksInfo.chunksTableName)}`;
+                const parentFk = sql.identifier(chunksInfo.parentFkField);
+                const chunkContentField = sql.identifier(chunksInfo.contentField);
+                const parentId = sql `${alias}.${sql.identifier(chunksInfo.parentPkField)}`;
+                const chunksAlias = sql.identifier('__bm25_chunks');
+                // BM25 on chunks requires an index name on the chunks table.
+                // We construct it from the chunks table schema + a conventional index name.
+                // The BM25 index on chunks is named: {chunks_table}_{content_field}_bm25_idx
+                const chunksIndexName = `"${chunksInfo.chunksSchema || bm25Index.schemaName}"."${chunksInfo.chunksTableName}_${chunksInfo.contentField}_bm25_idx"`;
+                const chunkBm25queryExpr = sql `to_bm25query(${sql.value(query)}, ${sql.value(chunksIndexName)})`;
+                const chunkScoreExpr = sql `(${chunksAlias}.${chunkContentField} <@> ${chunkBm25queryExpr})`;
+                // Subquery: MIN(bm25_score) across chunks (lower = better for BM25)
+                const chunkScoreSubquery = sql `(
+          SELECT MIN(${chunkScoreExpr})
+          FROM ${chunksTableRef} AS ${chunksAlias}
+          WHERE ${chunksAlias}.${parentFk} = ${parentId}
+        )`;
+                // Combined: LEAST of parent score and best chunk score (lower = better)
+                const combinedScoreExpr = sql `LEAST(
+          COALESCE(${scoreExpr}, 0::real),
+          COALESCE(${chunkScoreSubquery}, 0::real)
+        )`;
+                let whereClause = null;
+                if (threshold !== undefined && threshold !== null) {
+                    whereClause = sql `${combinedScoreExpr} < ${sql.value(threshold)}`;
+                }
+                return {
+                    whereClause,
+                    scoreExpression: combinedScoreExpr,
+                };
+            }
+            // Standard (non-chunk) query
             let whereClause = null;
             if (threshold !== undefined && threshold !== null) {
                 whereClause = sql `${scoreExpr} < ${sql.value(threshold)}`;

package/adapters/chunks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared @hasChunks smart tag utilities.
+ *
+ * Extracts chunk table metadata from the @hasChunks smart tag on a codec.
+ * Used by pgvector, tsvector, BM25, and trgm adapters to build lateral
+ * subqueries against the chunks table for chunk-aware search.
+ */
+/**
+ * Chunks table info detected from @hasChunks smart tag.
+ */
+export interface ChunksInfo {
+    chunksSchema: string | null;
+    chunksTableName: string;
+    parentFkField: string;
+    parentPkField: string;
+    embeddingField: string;
+    /** Text content field on chunks table (e.g. "content") */
+    contentField: string;
+    /** tsvector field on chunks table, if fulltext search is enabled (e.g. "search") */
+    searchField: string | null;
+    /** Which search indexes are created on the chunks table (e.g. ["fulltext", "bm25"]) */
+    searchIndexes: string[];
+}
+/**
+ * Read @hasChunks smart tag from codec extensions.
+ *
+ * The tag value is a JSON object like:
+ * {
+ *   "chunksTable": "documents_chunks",
+ *   "chunksSchema": "app_private",    // optional, defaults to parent table's schema
+ *   "parentFk": "document_id",         // optional, defaults to "parent_id"
+ *   "parentPk": "id",                  // optional, defaults to "id"
+ *   "embeddingField": "embedding",     // optional, defaults to "embedding"
+ *   "contentField": "content",         // optional, defaults to "content"
+ *   "searchField": "search",           // optional, null if no fulltext
+ *   "searchIndexes": ["fulltext","bm25"] // optional, defaults to []
+ * }
+ */
+export declare function getChunksInfo(codec: any): ChunksInfo | undefined;

package/adapters/chunks.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Shared @hasChunks smart tag utilities.
+ *
+ * Extracts chunk table metadata from the @hasChunks smart tag on a codec.
+ * Used by pgvector, tsvector, BM25, and trgm adapters to build lateral
+ * subqueries against the chunks table for chunk-aware search.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getChunksInfo = getChunksInfo;
+/**
+ * Read @hasChunks smart tag from codec extensions.
+ *
+ * The tag value is a JSON object like:
+ * {
+ *   "chunksTable": "documents_chunks",
+ *   "chunksSchema": "app_private",    // optional, defaults to parent table's schema
+ *   "parentFk": "document_id",         // optional, defaults to "parent_id"
+ *   "parentPk": "id",                  // optional, defaults to "id"
+ *   "embeddingField": "embedding",     // optional, defaults to "embedding"
+ *   "contentField": "content",         // optional, defaults to "content"
+ *   "searchField": "search",           // optional, null if no fulltext
+ *   "searchIndexes": ["fulltext","bm25"] // optional, defaults to []
+ * }
+ */
+function getChunksInfo(codec) {
+    const tags = codec?.extensions?.tags;
+    if (!tags)
+        return undefined;
+    const raw = tags.hasChunks;
+    if (!raw)
+        return undefined;
+    let parsed;
+    if (typeof raw === 'string') {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else if (typeof raw === 'object') {
+        parsed = raw;
+    }
+    else if (raw === true) {
+        return undefined;
+    }
+    else {
+        return undefined;
+    }
+    if (!parsed.chunksTable)
+        return undefined;
+    const chunksSchema = parsed.chunksSchema
+        || codec?.extensions?.pg?.schemaName
+        || null;
+    // Parse searchIndexes from tag (may be array or JSON string)
+    let searchIndexes = [];
+    if (Array.isArray(parsed.searchIndexes)) {
+        searchIndexes = parsed.searchIndexes;
+    }
+    else if (typeof parsed.searchIndexes === 'string') {
+        try {
+            const arr = JSON.parse(parsed.searchIndexes);
+            if (Array.isArray(arr))
+                searchIndexes = arr;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return {
+        chunksSchema,
+        chunksTableName: parsed.chunksTable,
+        parentFkField: parsed.parentFk || 'parent_id',
+        parentPkField: parsed.parentPk || 'id',
+        embeddingField: parsed.embeddingField || 'embedding',
+        contentField: parsed.contentField || 'content',
+        searchField: parsed.searchField || null,
+        searchIndexes,
+    };
+}

package/adapters/index.d.ts

@@ -12,3 +12,5 @@ export { createTrgmAdapter } from './trgm';
 export type { TrgmAdapterOptions } from './trgm';
 export { createPgvectorAdapter } from './pgvector';
 export type { PgvectorAdapterOptions } from './pgvector';
+export { getChunksInfo } from './chunks';
+export type { ChunksInfo } from './chunks';

package/adapters/index.js

@@ -6,7 +6,7 @@
  * search algorithm. They are plain objects — not Graphile plugins.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createPgvectorAdapter = exports.createTrgmAdapter = exports.createBm25Adapter = exports.createTsvectorAdapter = void 0;
+exports.getChunksInfo = exports.createPgvectorAdapter = exports.createTrgmAdapter = exports.createBm25Adapter = exports.createTsvectorAdapter = void 0;
 var tsvector_1 = require("./tsvector");
 Object.defineProperty(exports, "createTsvectorAdapter", { enumerable: true, get: function () { return tsvector_1.createTsvectorAdapter; } });
 var bm25_1 = require("./bm25");
@@ -15,3 +15,5 @@ var trgm_1 = require("./trgm");
 Object.defineProperty(exports, "createTrgmAdapter", { enumerable: true, get: function () { return trgm_1.createTrgmAdapter; } });
 var pgvector_1 = require("./pgvector");
 Object.defineProperty(exports, "createPgvectorAdapter", { enumerable: true, get: function () { return pgvector_1.createPgvectorAdapter; } });
+var chunks_1 = require("./chunks");
+Object.defineProperty(exports, "getChunksInfo", { enumerable: true, get: function () { return chunks_1.getChunksInfo; } });

package/adapters/pgvector.js

@@ -8,6 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPgvectorAdapter = createPgvectorAdapter;
+const chunks_1 = require("./chunks");
 /**
  * Build a distance expression for the given metric.
  * Uses explicit SQL template literals for each operator to avoid sql.raw.
@@ -26,57 +27,6 @@ function buildDistanceExpr(sql, columnExpr, vectorExpr, metric) {
 function isVectorCodec(codec) {
     return codec?.name === 'vector';
 }
-/**
- * Read @hasChunks smart tag from codec extensions.
- * The tag value is a JSON object like:
- * {
- *   "chunksTable": "documents_chunks",
- *   "chunksSchema": "app_private",    // optional, defaults to parent table's schema
- *   "parentFk": "document_id",         // optional, defaults to "parent_id"
- *   "parentPk": "id",                  // optional, defaults to "id"
- *   "embeddingField": "embedding"       // optional, defaults to "embedding"
- * }
- */
-function getChunksInfo(codec) {
-    const tags = codec?.extensions?.tags;
-    if (!tags)
-        return undefined;
-    const raw = tags.hasChunks;
-    if (!raw)
-        return undefined;
-    let parsed;
-    if (typeof raw === 'string') {
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            // If it's just "true" or a plain string, use convention-based defaults
-            return undefined;
-        }
-    }
-    else if (typeof raw === 'object') {
-        parsed = raw;
-    }
-    else if (raw === true) {
-        return undefined; // boolean true = no metadata, can't resolve
-    }
-    else {
-        return undefined;
-    }
-    if (!parsed.chunksTable)
-        return undefined;
-    // Resolve schema: explicit chunksSchema > parent codec schema > null
-    const chunksSchema = parsed.chunksSchema
-        || codec?.extensions?.pg?.schemaName
-        || null;
-    return {
-        chunksSchema,
-        chunksTableName: parsed.chunksTable,
-        parentFkField: parsed.parentFk || 'parent_id',
-        parentPkField: parsed.parentPk || 'id',
-        embeddingField: parsed.embeddingField || 'embedding',
-    };
-}
 function createPgvectorAdapter(options = {}) {
     const { filterPrefix = 'vector', defaultMetric = 'COSINE', enableChunkQuerying = true } = options;
     return {
@@ -96,7 +46,7 @@ function createPgvectorAdapter(options = {}) {
             if (!codec?.attributes)
                 return [];
             const columns = [];
-            const chunksInfo = enableChunkQuerying ? getChunksInfo(codec) : undefined;
+            const chunksInfo = enableChunkQuerying ? (0, chunks_1.getChunksInfo)(codec) : undefined;
             for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
                 if (isVectorCodec(attribute.codec)) {
                     columns.push({

package/adapters/trgm.d.ts

@@ -3,6 +3,11 @@
  *
  * Detects text/varchar columns and generates trigram similarity scoring.
  * Wraps the same SQL logic as graphile-trgm but as a SearchAdapter.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a trigram index, the adapter includes a lateral
+ * subquery to find the best-matching chunk and returns
+ * GREATEST(parent_similarity, chunk_similarity).
  */
 import type { SearchAdapter } from '../types';
 export interface TrgmAdapterOptions {

package/adapters/trgm.js

@@ -4,9 +4,15 @@
  *
  * Detects text/varchar columns and generates trigram similarity scoring.
  * Wraps the same SQL logic as graphile-trgm but as a SearchAdapter.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a trigram index, the adapter includes a lateral
+ * subquery to find the best-matching chunk and returns
+ * GREATEST(parent_similarity, chunk_similarity).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTrgmAdapter = createTrgmAdapter;
+const chunks_1 = require("./chunks");
 function isTextCodec(codec) {
     const name = codec?.name;
     return name === 'text' || name === 'varchar' || name === 'bpchar';
@@ -37,7 +43,13 @@ function createTrgmAdapter(options = {}) {
             const columns = [];
             for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
                 if (isTextCodec(attribute.codec)) {
-                    columns.push({ attributeName });
+                    // Store chunks info if available and chunks have trigram search
+                    const chunksInfo = (0, chunks_1.getChunksInfo)(codec);
+                    const hasChunkTrgm = chunksInfo?.searchIndexes.includes('trigram');
+                    columns.push({
+                        attributeName,
+                        adapterData: hasChunkTrgm ? chunksInfo : undefined,
+                    });
                 }
             }
             return columns;
@@ -73,12 +85,42 @@ function createTrgmAdapter(options = {}) {
         buildFilterApply(sql, alias, column, filterValue, _build) {
             if (filterValue == null)
                 return null;
-            const { value, threshold } = filterValue;
+            const { value, threshold, includeChunks } = filterValue;
             if (!value || typeof value !== 'string' || value.trim().length === 0)
                 return null;
             const th = threshold != null ? threshold : defaultThreshold;
             const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
             const similarityExpr = sql `similarity(${columnExpr}, ${sql.value(value)})`;
+            // Check for chunk-aware querying
+            const chunksInfo = column.adapterData;
+            if (chunksInfo && chunksInfo.searchIndexes.includes('trigram') && (includeChunks !== false)) {
+                const chunksTableRef = chunksInfo.chunksSchema
+                    ? sql `${sql.identifier(chunksInfo.chunksSchema)}.${sql.identifier(chunksInfo.chunksTableName)}`
+                    : sql `${sql.identifier(chunksInfo.chunksTableName)}`;
+                const parentFk = sql.identifier(chunksInfo.parentFkField);
+                const chunkContentField = sql.identifier(chunksInfo.contentField);
+                const parentId = sql `${alias}.${sql.identifier(chunksInfo.parentPkField)}`;
+                const chunksAlias = sql.identifier('__trgm_chunks');
+                // Subquery: MAX(similarity) across chunks (higher = better for trgm)
+                const chunkSimilaritySubquery = sql `(
+          SELECT MAX(similarity(${chunksAlias}.${chunkContentField}, ${sql.value(value)}))
+          FROM ${chunksTableRef} AS ${chunksAlias}
+          WHERE ${chunksAlias}.${parentFk} = ${parentId}
+            AND similarity(${chunksAlias}.${chunkContentField}, ${sql.value(value)}) > ${sql.value(th)}
+        )`;
+                // Combined: GREATEST of parent similarity and best chunk similarity
+                const combinedSimilarityExpr = sql `GREATEST(
+          COALESCE(${similarityExpr}, 0::real),
+          COALESCE(${chunkSimilaritySubquery}, 0::real)
+        )`;
+                // WHERE: parent matches OR any chunk matches
+                const whereClause = sql `(${similarityExpr} > ${sql.value(th)} OR ${chunkSimilaritySubquery} IS NOT NULL)`;
+                return {
+                    whereClause,
+                    scoreExpression: combinedSimilarityExpr,
+                };
+            }
+            // Standard (non-chunk) query
             return {
                 whereClause: sql `${similarityExpr} > ${sql.value(th)}`,
                 scoreExpression: similarityExpr,

package/adapters/tsvector.d.ts

@@ -3,6 +3,11 @@
  *
  * Detects tsvector columns and generates ts_rank-based scoring.
  * Wraps the same SQL logic as graphile-tsvector but as a SearchAdapter.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a tsvector search field, the adapter includes a
+ * lateral subquery to find the best-matching chunk and returns
+ * GREATEST(parent_rank, chunk_rank).
  */
 import type { SearchAdapter } from '../types';
 export interface TsvectorAdapterOptions {

package/adapters/tsvector.js

@@ -4,9 +4,15 @@
  *
  * Detects tsvector columns and generates ts_rank-based scoring.
  * Wraps the same SQL logic as graphile-tsvector but as a SearchAdapter.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a tsvector search field, the adapter includes a
+ * lateral subquery to find the best-matching chunk and returns
+ * GREATEST(parent_rank, chunk_rank).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTsvectorAdapter = createTsvectorAdapter;
+const chunks_1 = require("./chunks");
 function isTsvectorCodec(codec) {
     // In graphile-build-pg >= 5.0.0-rc.8, the built-in TYPES.tsvector codec
     // has name === 'tsvector' but does NOT have extensions.pg. We need to
@@ -36,7 +42,14 @@ function createTsvectorAdapter(options = {}) {
             const columns = [];
             for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
                 if (isTsvectorCodec(attribute.codec)) {
-                    columns.push({ attributeName });
+                    // Store chunks info if available and chunks have fulltext search
+                    const chunksInfo = (0, chunks_1.getChunksInfo)(codec);
+                    const hasChunkFulltext = chunksInfo?.searchField &&
+                        chunksInfo.searchIndexes.includes('fulltext');
+                    columns.push({
+                        attributeName,
+                        adapterData: hasChunkFulltext ? chunksInfo : undefined,
+                    });
                 }
             }
             return columns;
@@ -50,11 +63,51 @@ function createTsvectorAdapter(options = {}) {
         buildFilterApply(sql, alias, column, filterValue, _build) {
             if (filterValue == null)
                 return null;
-            const val = typeof filterValue === 'string' ? filterValue : String(filterValue);
+            // Handle includeChunks option when filter is an object
+            let val;
+            let includeChunks;
+            if (typeof filterValue === 'object' && filterValue !== null && 'query' in filterValue) {
+                val = typeof filterValue.query === 'string' ? filterValue.query : String(filterValue.query);
+                includeChunks = filterValue.includeChunks;
+            }
+            else {
+                val = typeof filterValue === 'string' ? filterValue : String(filterValue);
+            }
             if (val.trim().length === 0)
                 return null;
             const tsquery = sql `websearch_to_tsquery(${sql.literal(tsConfig)}, ${sql.value(val)})`;
             const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
+            // Check for chunk-aware querying
+            const chunksInfo = column.adapterData;
+            if (chunksInfo && chunksInfo.searchField && (includeChunks !== false)) {
+                const chunksTableRef = chunksInfo.chunksSchema
+                    ? sql `${sql.identifier(chunksInfo.chunksSchema)}.${sql.identifier(chunksInfo.chunksTableName)}`
+                    : sql `${sql.identifier(chunksInfo.chunksTableName)}`;
+                const parentFk = sql.identifier(chunksInfo.parentFkField);
+                const chunkSearchField = sql.identifier(chunksInfo.searchField);
+                const parentId = sql `${alias}.${sql.identifier(chunksInfo.parentPkField)}`;
+                const chunksAlias = sql.identifier('__tsv_chunks');
+                // Subquery: MAX(ts_rank) across matching chunks
+                const chunkRankSubquery = sql `(
+          SELECT MAX(ts_rank(${chunksAlias}.${chunkSearchField}, ${tsquery}))
+          FROM ${chunksTableRef} AS ${chunksAlias}
+          WHERE ${chunksAlias}.${parentFk} = ${parentId}
+            AND ${chunksAlias}.${chunkSearchField} @@ ${tsquery}
+        )`;
+                const parentRankExpr = sql `ts_rank(${columnExpr}, ${tsquery})`;
+                // Combined: GREATEST of parent rank and best chunk rank
+                const combinedRankExpr = sql `GREATEST(
+          COALESCE(CASE WHEN ${columnExpr} @@ ${tsquery} THEN ${parentRankExpr} ELSE 0::real END, 0::real),
+          COALESCE(${chunkRankSubquery}, 0::real)
+        )`;
+                // WHERE: parent matches OR any chunk matches
+                const whereClause = sql `(${columnExpr} @@ ${tsquery} OR ${chunkRankSubquery} IS NOT NULL)`;
+                return {
+                    whereClause,
+                    scoreExpression: combinedRankExpr,
+                };
+            }
+            // Standard (non-chunk) query
             return {
                 whereClause: sql `${columnExpr} @@ ${tsquery}`,
                 scoreExpression: sql `ts_rank(${columnExpr}, ${tsquery})`,

package/esm/adapters/bm25.d.ts

@@ -6,6 +6,11 @@
  *
  * Requires the Bm25CodecPlugin to be loaded first (for index discovery).
  * The adapter reads from the bm25IndexStore populated during the gather phase.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a BM25 index, the adapter includes a lateral
+ * subquery to find the best-matching chunk and returns
+ * LEAST(parent_score, chunk_score) (lower = better for BM25).
  */
 import type { SearchAdapter } from '../types';
 /**

package/esm/adapters/bm25.js

@@ -6,8 +6,14 @@
  *
  * Requires the Bm25CodecPlugin to be loaded first (for index discovery).
  * The adapter reads from the bm25IndexStore populated during the gather phase.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a BM25 index, the adapter includes a lateral
+ * subquery to find the best-matching chunk and returns
+ * LEAST(parent_score, chunk_score) (lower = better for BM25).
  */
 import { bm25IndexStore as moduleBm25IndexStore } from '../codecs/bm25-codec';
+import { getChunksInfo } from './chunks';
 function isTextCodec(codec) {
     const name = codec?.name;
     return name === 'text' || name === 'varchar' || name === 'bpchar';
@@ -59,7 +65,14 @@ export function createBm25Adapter(options = {}) {
                 const bm25Index = getBm25IndexForAttribute(codec, attributeName, build);
                 if (!bm25Index)
                     continue;
-                columns.push({ attributeName, adapterData: bm25Index });
+                // Check for chunk-aware BM25
+                const chunksInfo = getChunksInfo(codec);
+                const hasChunkBm25 = chunksInfo?.searchIndexes.includes('bm25');
+                const columnData = {
+                    bm25Index,
+                    chunksInfo: hasChunkBm25 ? chunksInfo : undefined,
+                };
+                columns.push({ attributeName, adapterData: columnData });
             }
             return columns;
         },
@@ -94,15 +107,53 @@ export function createBm25Adapter(options = {}) {
         buildFilterApply(sql, alias, column, filterValue, _build) {
             if (filterValue == null)
                 return null;
-            const { query, threshold } = filterValue;
+            const { query, threshold, includeChunks } = filterValue;
             if (!query || typeof query !== 'string' || query.trim().length === 0)
                 return null;
-            const bm25Index = column.adapterData;
+            const columnData = column.adapterData;
+            const bm25Index = columnData.bm25Index;
             const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
             // Use quoteQualifiedIdentifier to produce the qualified index name
             const qualifiedIndexName = `"${bm25Index.schemaName}"."${bm25Index.indexName}"`;
             const bm25queryExpr = sql `to_bm25query(${sql.value(query)}, ${sql.value(qualifiedIndexName)})`;
             const scoreExpr = sql `(${columnExpr} <@> ${bm25queryExpr})`;
+            // Check for chunk-aware querying
+            const chunksInfo = columnData.chunksInfo;
+            if (chunksInfo && chunksInfo.searchIndexes.includes('bm25') && (includeChunks !== false)) {
+                const chunksTableRef = chunksInfo.chunksSchema
+                    ? sql `${sql.identifier(chunksInfo.chunksSchema)}.${sql.identifier(chunksInfo.chunksTableName)}`
+                    : sql `${sql.identifier(chunksInfo.chunksTableName)}`;
+                const parentFk = sql.identifier(chunksInfo.parentFkField);
+                const chunkContentField = sql.identifier(chunksInfo.contentField);
+                const parentId = sql `${alias}.${sql.identifier(chunksInfo.parentPkField)}`;
+                const chunksAlias = sql.identifier('__bm25_chunks');
+                // BM25 on chunks requires an index name on the chunks table.
+                // We construct it from the chunks table schema + a conventional index name.
+                // The BM25 index on chunks is named: {chunks_table}_{content_field}_bm25_idx
+                const chunksIndexName = `"${chunksInfo.chunksSchema || bm25Index.schemaName}"."${chunksInfo.chunksTableName}_${chunksInfo.contentField}_bm25_idx"`;
+                const chunkBm25queryExpr = sql `to_bm25query(${sql.value(query)}, ${sql.value(chunksIndexName)})`;
+                const chunkScoreExpr = sql `(${chunksAlias}.${chunkContentField} <@> ${chunkBm25queryExpr})`;
+                // Subquery: MIN(bm25_score) across chunks (lower = better for BM25)
+                const chunkScoreSubquery = sql `(
+          SELECT MIN(${chunkScoreExpr})
+          FROM ${chunksTableRef} AS ${chunksAlias}
+          WHERE ${chunksAlias}.${parentFk} = ${parentId}
+        )`;
+                // Combined: LEAST of parent score and best chunk score (lower = better)
+                const combinedScoreExpr = sql `LEAST(
+          COALESCE(${scoreExpr}, 0::real),
+          COALESCE(${chunkScoreSubquery}, 0::real)
+        )`;
+                let whereClause = null;
+                if (threshold !== undefined && threshold !== null) {
+                    whereClause = sql `${combinedScoreExpr} < ${sql.value(threshold)}`;
+                }
+                return {
+                    whereClause,
+                    scoreExpression: combinedScoreExpr,
+                };
+            }
+            // Standard (non-chunk) query
             let whereClause = null;
             if (threshold !== undefined && threshold !== null) {
                 whereClause = sql `${scoreExpr} < ${sql.value(threshold)}`;

package/esm/adapters/chunks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared @hasChunks smart tag utilities.
+ *
+ * Extracts chunk table metadata from the @hasChunks smart tag on a codec.
+ * Used by pgvector, tsvector, BM25, and trgm adapters to build lateral
+ * subqueries against the chunks table for chunk-aware search.
+ */
+/**
+ * Chunks table info detected from @hasChunks smart tag.
+ */
+export interface ChunksInfo {
+    chunksSchema: string | null;
+    chunksTableName: string;
+    parentFkField: string;
+    parentPkField: string;
+    embeddingField: string;
+    /** Text content field on chunks table (e.g. "content") */
+    contentField: string;
+    /** tsvector field on chunks table, if fulltext search is enabled (e.g. "search") */
+    searchField: string | null;
+    /** Which search indexes are created on the chunks table (e.g. ["fulltext", "bm25"]) */
+    searchIndexes: string[];
+}
+/**
+ * Read @hasChunks smart tag from codec extensions.
+ *
+ * The tag value is a JSON object like:
+ * {
+ *   "chunksTable": "documents_chunks",
+ *   "chunksSchema": "app_private",    // optional, defaults to parent table's schema
+ *   "parentFk": "document_id",         // optional, defaults to "parent_id"
+ *   "parentPk": "id",                  // optional, defaults to "id"
+ *   "embeddingField": "embedding",     // optional, defaults to "embedding"
+ *   "contentField": "content",         // optional, defaults to "content"
+ *   "searchField": "search",           // optional, null if no fulltext
+ *   "searchIndexes": ["fulltext","bm25"] // optional, defaults to []
+ * }
+ */
+export declare function getChunksInfo(codec: any): ChunksInfo | undefined;

package/esm/adapters/chunks.js

@@ -0,0 +1,78 @@
+/**
+ * Shared @hasChunks smart tag utilities.
+ *
+ * Extracts chunk table metadata from the @hasChunks smart tag on a codec.
+ * Used by pgvector, tsvector, BM25, and trgm adapters to build lateral
+ * subqueries against the chunks table for chunk-aware search.
+ */
+/**
+ * Read @hasChunks smart tag from codec extensions.
+ *
+ * The tag value is a JSON object like:
+ * {
+ *   "chunksTable": "documents_chunks",
+ *   "chunksSchema": "app_private",    // optional, defaults to parent table's schema
+ *   "parentFk": "document_id",         // optional, defaults to "parent_id"
+ *   "parentPk": "id",                  // optional, defaults to "id"
+ *   "embeddingField": "embedding",     // optional, defaults to "embedding"
+ *   "contentField": "content",         // optional, defaults to "content"
+ *   "searchField": "search",           // optional, null if no fulltext
+ *   "searchIndexes": ["fulltext","bm25"] // optional, defaults to []
+ * }
+ */
+export function getChunksInfo(codec) {
+    const tags = codec?.extensions?.tags;
+    if (!tags)
+        return undefined;
+    const raw = tags.hasChunks;
+    if (!raw)
+        return undefined;
+    let parsed;
+    if (typeof raw === 'string') {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else if (typeof raw === 'object') {
+        parsed = raw;
+    }
+    else if (raw === true) {
+        return undefined;
+    }
+    else {
+        return undefined;
+    }
+    if (!parsed.chunksTable)
+        return undefined;
+    const chunksSchema = parsed.chunksSchema
+        || codec?.extensions?.pg?.schemaName
+        || null;
+    // Parse searchIndexes from tag (may be array or JSON string)
+    let searchIndexes = [];
+    if (Array.isArray(parsed.searchIndexes)) {
+        searchIndexes = parsed.searchIndexes;
+    }
+    else if (typeof parsed.searchIndexes === 'string') {
+        try {
+            const arr = JSON.parse(parsed.searchIndexes);
+            if (Array.isArray(arr))
+                searchIndexes = arr;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return {
+        chunksSchema,
+        chunksTableName: parsed.chunksTable,
+        parentFkField: parsed.parentFk || 'parent_id',
+        parentPkField: parsed.parentPk || 'id',
+        embeddingField: parsed.embeddingField || 'embedding',
+        contentField: parsed.contentField || 'content',
+        searchField: parsed.searchField || null,
+        searchIndexes,
+    };
+}

package/esm/adapters/index.d.ts

@@ -12,3 +12,5 @@ export { createTrgmAdapter } from './trgm';
 export type { TrgmAdapterOptions } from './trgm';
 export { createPgvectorAdapter } from './pgvector';
 export type { PgvectorAdapterOptions } from './pgvector';
+export { getChunksInfo } from './chunks';
+export type { ChunksInfo } from './chunks';

package/esm/adapters/index.js

@@ -8,3 +8,4 @@ export { createTsvectorAdapter } from './tsvector';
 export { createBm25Adapter } from './bm25';
 export { createTrgmAdapter } from './trgm';
 export { createPgvectorAdapter } from './pgvector';
+export { getChunksInfo } from './chunks';

package/esm/adapters/pgvector.js

@@ -5,6 +5,7 @@
  * pgvector operators (<=> cosine, <-> L2, <#> inner product).
  * Wraps the same SQL logic as graphile-pgvector but as a SearchAdapter.
  */
+import { getChunksInfo } from './chunks';
 /**
  * Build a distance expression for the given metric.
  * Uses explicit SQL template literals for each operator to avoid sql.raw.
@@ -23,57 +24,6 @@ function buildDistanceExpr(sql, columnExpr, vectorExpr, metric) {
 function isVectorCodec(codec) {
     return codec?.name === 'vector';
 }
-/**
- * Read @hasChunks smart tag from codec extensions.
- * The tag value is a JSON object like:
- * {
- *   "chunksTable": "documents_chunks",
- *   "chunksSchema": "app_private",    // optional, defaults to parent table's schema
- *   "parentFk": "document_id",         // optional, defaults to "parent_id"
- *   "parentPk": "id",                  // optional, defaults to "id"
- *   "embeddingField": "embedding"       // optional, defaults to "embedding"
- * }
- */
-function getChunksInfo(codec) {
-    const tags = codec?.extensions?.tags;
-    if (!tags)
-        return undefined;
-    const raw = tags.hasChunks;
-    if (!raw)
-        return undefined;
-    let parsed;
-    if (typeof raw === 'string') {
-        try {
-            parsed = JSON.parse(raw);
-        }
-        catch {
-            // If it's just "true" or a plain string, use convention-based defaults
-            return undefined;
-        }
-    }
-    else if (typeof raw === 'object') {
-        parsed = raw;
-    }
-    else if (raw === true) {
-        return undefined; // boolean true = no metadata, can't resolve
-    }
-    else {
-        return undefined;
-    }
-    if (!parsed.chunksTable)
-        return undefined;
-    // Resolve schema: explicit chunksSchema > parent codec schema > null
-    const chunksSchema = parsed.chunksSchema
-        || codec?.extensions?.pg?.schemaName
-        || null;
-    return {
-        chunksSchema,
-        chunksTableName: parsed.chunksTable,
-        parentFkField: parsed.parentFk || 'parent_id',
-        parentPkField: parsed.parentPk || 'id',
-        embeddingField: parsed.embeddingField || 'embedding',
-    };
-}
 export function createPgvectorAdapter(options = {}) {
     const { filterPrefix = 'vector', defaultMetric = 'COSINE', enableChunkQuerying = true } = options;
     return {

package/esm/adapters/trgm.d.ts

@@ -3,6 +3,11 @@
  *
  * Detects text/varchar columns and generates trigram similarity scoring.
  * Wraps the same SQL logic as graphile-trgm but as a SearchAdapter.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a trigram index, the adapter includes a lateral
+ * subquery to find the best-matching chunk and returns
+ * GREATEST(parent_similarity, chunk_similarity).
  */
 import type { SearchAdapter } from '../types';
 export interface TrgmAdapterOptions {

package/esm/adapters/trgm.js

@@ -3,7 +3,13 @@
  *
  * Detects text/varchar columns and generates trigram similarity scoring.
  * Wraps the same SQL logic as graphile-trgm but as a SearchAdapter.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a trigram index, the adapter includes a lateral
+ * subquery to find the best-matching chunk and returns
+ * GREATEST(parent_similarity, chunk_similarity).
  */
+import { getChunksInfo } from './chunks';
 function isTextCodec(codec) {
     const name = codec?.name;
     return name === 'text' || name === 'varchar' || name === 'bpchar';
@@ -34,7 +40,13 @@ export function createTrgmAdapter(options = {}) {
             const columns = [];
             for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
                 if (isTextCodec(attribute.codec)) {
-                    columns.push({ attributeName });
+                    // Store chunks info if available and chunks have trigram search
+                    const chunksInfo = getChunksInfo(codec);
+                    const hasChunkTrgm = chunksInfo?.searchIndexes.includes('trigram');
+                    columns.push({
+                        attributeName,
+                        adapterData: hasChunkTrgm ? chunksInfo : undefined,
+                    });
                 }
             }
             return columns;
@@ -70,12 +82,42 @@ export function createTrgmAdapter(options = {}) {
         buildFilterApply(sql, alias, column, filterValue, _build) {
             if (filterValue == null)
                 return null;
-            const { value, threshold } = filterValue;
+            const { value, threshold, includeChunks } = filterValue;
             if (!value || typeof value !== 'string' || value.trim().length === 0)
                 return null;
             const th = threshold != null ? threshold : defaultThreshold;
             const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
             const similarityExpr = sql `similarity(${columnExpr}, ${sql.value(value)})`;
+            // Check for chunk-aware querying
+            const chunksInfo = column.adapterData;
+            if (chunksInfo && chunksInfo.searchIndexes.includes('trigram') && (includeChunks !== false)) {
+                const chunksTableRef = chunksInfo.chunksSchema
+                    ? sql `${sql.identifier(chunksInfo.chunksSchema)}.${sql.identifier(chunksInfo.chunksTableName)}`
+                    : sql `${sql.identifier(chunksInfo.chunksTableName)}`;
+                const parentFk = sql.identifier(chunksInfo.parentFkField);
+                const chunkContentField = sql.identifier(chunksInfo.contentField);
+                const parentId = sql `${alias}.${sql.identifier(chunksInfo.parentPkField)}`;
+                const chunksAlias = sql.identifier('__trgm_chunks');
+                // Subquery: MAX(similarity) across chunks (higher = better for trgm)
+                const chunkSimilaritySubquery = sql `(
+          SELECT MAX(similarity(${chunksAlias}.${chunkContentField}, ${sql.value(value)}))
+          FROM ${chunksTableRef} AS ${chunksAlias}
+          WHERE ${chunksAlias}.${parentFk} = ${parentId}
+            AND similarity(${chunksAlias}.${chunkContentField}, ${sql.value(value)}) > ${sql.value(th)}
+        )`;
+                // Combined: GREATEST of parent similarity and best chunk similarity
+                const combinedSimilarityExpr = sql `GREATEST(
+          COALESCE(${similarityExpr}, 0::real),
+          COALESCE(${chunkSimilaritySubquery}, 0::real)
+        )`;
+                // WHERE: parent matches OR any chunk matches
+                const whereClause = sql `(${similarityExpr} > ${sql.value(th)} OR ${chunkSimilaritySubquery} IS NOT NULL)`;
+                return {
+                    whereClause,
+                    scoreExpression: combinedSimilarityExpr,
+                };
+            }
+            // Standard (non-chunk) query
             return {
                 whereClause: sql `${similarityExpr} > ${sql.value(th)}`,
                 scoreExpression: similarityExpr,

package/esm/adapters/tsvector.d.ts

@@ -3,6 +3,11 @@
  *
  * Detects tsvector columns and generates ts_rank-based scoring.
  * Wraps the same SQL logic as graphile-tsvector but as a SearchAdapter.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a tsvector search field, the adapter includes a
+ * lateral subquery to find the best-matching chunk and returns
+ * GREATEST(parent_rank, chunk_rank).
  */
 import type { SearchAdapter } from '../types';
 export interface TsvectorAdapterOptions {

package/esm/adapters/tsvector.js

@@ -3,7 +3,13 @@
  *
  * Detects tsvector columns and generates ts_rank-based scoring.
  * Wraps the same SQL logic as graphile-tsvector but as a SearchAdapter.
+ *
+ * Supports chunk-aware querying via @hasChunks smart tag: when the parent
+ * table has chunks with a tsvector search field, the adapter includes a
+ * lateral subquery to find the best-matching chunk and returns
+ * GREATEST(parent_rank, chunk_rank).
  */
+import { getChunksInfo } from './chunks';
 function isTsvectorCodec(codec) {
     // In graphile-build-pg >= 5.0.0-rc.8, the built-in TYPES.tsvector codec
     // has name === 'tsvector' but does NOT have extensions.pg. We need to
@@ -33,7 +39,14 @@ export function createTsvectorAdapter(options = {}) {
             const columns = [];
             for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
                 if (isTsvectorCodec(attribute.codec)) {
-                    columns.push({ attributeName });
+                    // Store chunks info if available and chunks have fulltext search
+                    const chunksInfo = getChunksInfo(codec);
+                    const hasChunkFulltext = chunksInfo?.searchField &&
+                        chunksInfo.searchIndexes.includes('fulltext');
+                    columns.push({
+                        attributeName,
+                        adapterData: hasChunkFulltext ? chunksInfo : undefined,
+                    });
                 }
             }
             return columns;
@@ -47,11 +60,51 @@ export function createTsvectorAdapter(options = {}) {
         buildFilterApply(sql, alias, column, filterValue, _build) {
             if (filterValue == null)
                 return null;
-            const val = typeof filterValue === 'string' ? filterValue : String(filterValue);
+            // Handle includeChunks option when filter is an object
+            let val;
+            let includeChunks;
+            if (typeof filterValue === 'object' && filterValue !== null && 'query' in filterValue) {
+                val = typeof filterValue.query === 'string' ? filterValue.query : String(filterValue.query);
+                includeChunks = filterValue.includeChunks;
+            }
+            else {
+                val = typeof filterValue === 'string' ? filterValue : String(filterValue);
+            }
             if (val.trim().length === 0)
                 return null;
             const tsquery = sql `websearch_to_tsquery(${sql.literal(tsConfig)}, ${sql.value(val)})`;
             const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
+            // Check for chunk-aware querying
+            const chunksInfo = column.adapterData;
+            if (chunksInfo && chunksInfo.searchField && (includeChunks !== false)) {
+                const chunksTableRef = chunksInfo.chunksSchema
+                    ? sql `${sql.identifier(chunksInfo.chunksSchema)}.${sql.identifier(chunksInfo.chunksTableName)}`
+                    : sql `${sql.identifier(chunksInfo.chunksTableName)}`;
+                const parentFk = sql.identifier(chunksInfo.parentFkField);
+                const chunkSearchField = sql.identifier(chunksInfo.searchField);
+                const parentId = sql `${alias}.${sql.identifier(chunksInfo.parentPkField)}`;
+                const chunksAlias = sql.identifier('__tsv_chunks');
+                // Subquery: MAX(ts_rank) across matching chunks
+                const chunkRankSubquery = sql `(
+          SELECT MAX(ts_rank(${chunksAlias}.${chunkSearchField}, ${tsquery}))
+          FROM ${chunksTableRef} AS ${chunksAlias}
+          WHERE ${chunksAlias}.${parentFk} = ${parentId}
+            AND ${chunksAlias}.${chunkSearchField} @@ ${tsquery}
+        )`;
+                const parentRankExpr = sql `ts_rank(${columnExpr}, ${tsquery})`;
+                // Combined: GREATEST of parent rank and best chunk rank
+                const combinedRankExpr = sql `GREATEST(
+          COALESCE(CASE WHEN ${columnExpr} @@ ${tsquery} THEN ${parentRankExpr} ELSE 0::real END, 0::real),
+          COALESCE(${chunkRankSubquery}, 0::real)
+        )`;
+                // WHERE: parent matches OR any chunk matches
+                const whereClause = sql `(${columnExpr} @@ ${tsquery} OR ${chunkRankSubquery} IS NOT NULL)`;
+                return {
+                    whereClause,
+                    scoreExpression: combinedRankExpr,
+                };
+            }
+            // Standard (non-chunk) query
             return {
                 whereClause: sql `${columnExpr} @@ ${tsquery}`,
                 scoreExpression: sql `ts_rank(${columnExpr}, ${tsquery})`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-search",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Unified PostGraphile v5 search plugin — abstracts tsvector, BM25, pg_trgm, and pgvector behind a single adapter-based architecture with composite searchScore",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -31,11 +31,11 @@
   "devDependencies": {
     "@types/node": "^22.19.11",
     "@types/pg": "^8.18.0",
-    "graphile-connection-filter": "^1.10.0",
-    "graphile-test": "^4.15.0",
+    "graphile-connection-filter": "^1.10.1",
+    "graphile-test": "^4.15.1",
     "makage": "^0.3.0",
     "pg": "^8.20.0",
-    "pgsql-test": "^4.14.0"
+    "pgsql-test": "^4.14.1"
   },
   "peerDependencies": {
     "@dataplan/pg": "1.0.0",
@@ -62,5 +62,5 @@
     "hybrid-search",
     "searchScore"
   ],
-  "gitHead": "50dc1d69049c207b46c237eba1e1b1cb7a5f928f"
+  "gitHead": "1aaafe14a8ba4eeeaab099f5fdc69865ce4e2a2e"
 }