graphile-search 1.2.0 → 1.3.0

package/adapters/pgvector.d.ts

@@ -17,5 +17,13 @@ export interface PgvectorAdapterOptions {
      * @default 'COSINE'
      */
     defaultMetric?: 'COSINE' | 'L2' | 'IP';
+    /**
+     * When true, tables with @hasChunks smart tag will transparently
+     * query through the chunks table to find the closest chunk.
+     * The parent row's vector distance is the minimum distance across
+     * all its chunks.
+     * @default true
+     */
+    enableChunkQuerying?: boolean;
 }
 export declare function createPgvectorAdapter(options?: PgvectorAdapterOptions): SearchAdapter;

package/adapters/pgvector.js

@@ -19,8 +19,59 @@ const METRIC_OPERATORS = {
 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' } = options;
+    const { filterPrefix = 'vector', defaultMetric = 'COSINE', enableChunkQuerying = true } = options;
     return {
         name: 'vector',
         scoreSemantics: {
@@ -38,9 +89,13 @@ function createPgvectorAdapter(options = {}) {
             if (!codec?.attributes)
                 return [];
             const columns = [];
+            const chunksInfo = enableChunkQuerying ? getChunksInfo(codec) : undefined;
             for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
                 if (isVectorCodec(attribute.codec)) {
-                    columns.push({ attributeName });
+                    columns.push({
+                        attributeName,
+                        adapterData: chunksInfo ? { chunksInfo } : undefined,
+                    });
                 }
             }
             return columns;
@@ -92,6 +147,12 @@ function createPgvectorAdapter(options = {}) {
                                 type: GraphQLFloat,
                                 description: 'Maximum distance threshold. Only rows within this distance are returned.',
                             },
+                            includeChunks: {
+                                type: build.graphql.GraphQLBoolean,
+                                description: 'When true (default for tables with @hasChunks), transparently queries ' +
+                                    'the chunks table and returns the minimum distance across parent + all chunks. ' +
+                                    'Set to false to only search the parent embedding.',
+                            },
                         };
                     },
                 }), 'UnifiedSearchPlugin (pgvector adapter) registering VectorNearbyInput type');
@@ -106,14 +167,54 @@ function createPgvectorAdapter(options = {}) {
         buildFilterApply(sql, alias, column, filterValue, _build) {
             if (filterValue == null)
                 return null;
-            const { vector, metric, distance } = filterValue;
+            const { vector, metric, distance, includeChunks } = filterValue;
             if (!vector || !Array.isArray(vector) || vector.length === 0)
                 return null;
             const resolvedMetric = metric || defaultMetric;
             const operator = METRIC_OPERATORS[resolvedMetric] || METRIC_OPERATORS.COSINE;
             const vectorString = `[${vector.join(',')}]`;
-            const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
             const vectorExpr = sql `${sql.value(vectorString)}::vector`;
+            // Check if this column has chunks info and chunk querying is requested
+            const adapterData = column.adapterData;
+            const chunksInfo = adapterData?.chunksInfo;
+            if (chunksInfo && (includeChunks !== false)) {
+                // Chunk-aware query: find the closest chunk for each parent row
+                // Uses a lateral subquery to get the minimum distance across all chunks
+                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 chunkEmbedding = sql.identifier(chunksInfo.embeddingField);
+                // Use the configured PK field (defaults to 'id', but can be overridden via @hasChunks tag)
+                const parentId = sql `${alias}.${sql.identifier(chunksInfo.parentPkField)}`;
+                // Alias to avoid ambiguity when the chunks table name might collide
+                const chunksAlias = sql.identifier('__chunks');
+                // Subquery: SELECT MIN(distance) FROM chunks WHERE chunks.parent_fk = parent.pk
+                const chunkDistanceSubquery = sql `(
+          SELECT MIN(${chunksAlias}.${chunkEmbedding} ${sql.raw(operator)} ${vectorExpr})
+          FROM ${chunksTableRef} AS ${chunksAlias}
+          WHERE ${chunksAlias}.${parentFk} = ${parentId}
+        )`;
+                // Also compute direct parent distance if the parent has an embedding
+                const parentColumnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
+                const parentDistanceExpr = sql `(${parentColumnExpr} ${sql.raw(operator)} ${vectorExpr})`;
+                // 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)
+        )`;
+                let whereClause = null;
+                if (distance !== undefined && distance !== null) {
+                    whereClause = sql `${combinedDistanceExpr} <= ${sql.value(distance)}`;
+                }
+                return {
+                    whereClause,
+                    scoreExpression: combinedDistanceExpr,
+                };
+            }
+            // Standard (non-chunk) query
+            const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
             const distanceExpr = sql `(${columnExpr} ${sql.raw(operator)} ${vectorExpr})`;
             let whereClause = null;
             if (distance !== undefined && distance !== null) {

package/esm/adapters/pgvector.d.ts

@@ -17,5 +17,13 @@ export interface PgvectorAdapterOptions {
      * @default 'COSINE'
      */
     defaultMetric?: 'COSINE' | 'L2' | 'IP';
+    /**
+     * When true, tables with @hasChunks smart tag will transparently
+     * query through the chunks table to find the closest chunk.
+     * The parent row's vector distance is the minimum distance across
+     * all its chunks.
+     * @default true
+     */
+    enableChunkQuerying?: boolean;
 }
 export declare function createPgvectorAdapter(options?: PgvectorAdapterOptions): SearchAdapter;

package/esm/adapters/pgvector.js

@@ -16,8 +16,59 @@ const METRIC_OPERATORS = {
 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' } = options;
+    const { filterPrefix = 'vector', defaultMetric = 'COSINE', enableChunkQuerying = true } = options;
     return {
         name: 'vector',
         scoreSemantics: {
@@ -35,9 +86,13 @@ export function createPgvectorAdapter(options = {}) {
             if (!codec?.attributes)
                 return [];
             const columns = [];
+            const chunksInfo = enableChunkQuerying ? getChunksInfo(codec) : undefined;
             for (const [attributeName, attribute] of Object.entries(codec.attributes)) {
                 if (isVectorCodec(attribute.codec)) {
-                    columns.push({ attributeName });
+                    columns.push({
+                        attributeName,
+                        adapterData: chunksInfo ? { chunksInfo } : undefined,
+                    });
                 }
             }
             return columns;
@@ -89,6 +144,12 @@ export function createPgvectorAdapter(options = {}) {
                                 type: GraphQLFloat,
                                 description: 'Maximum distance threshold. Only rows within this distance are returned.',
                             },
+                            includeChunks: {
+                                type: build.graphql.GraphQLBoolean,
+                                description: 'When true (default for tables with @hasChunks), transparently queries ' +
+                                    'the chunks table and returns the minimum distance across parent + all chunks. ' +
+                                    'Set to false to only search the parent embedding.',
+                            },
                         };
                     },
                 }), 'UnifiedSearchPlugin (pgvector adapter) registering VectorNearbyInput type');
@@ -103,14 +164,54 @@ export function createPgvectorAdapter(options = {}) {
         buildFilterApply(sql, alias, column, filterValue, _build) {
             if (filterValue == null)
                 return null;
-            const { vector, metric, distance } = filterValue;
+            const { vector, metric, distance, includeChunks } = filterValue;
             if (!vector || !Array.isArray(vector) || vector.length === 0)
                 return null;
             const resolvedMetric = metric || defaultMetric;
             const operator = METRIC_OPERATORS[resolvedMetric] || METRIC_OPERATORS.COSINE;
             const vectorString = `[${vector.join(',')}]`;
-            const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
             const vectorExpr = sql `${sql.value(vectorString)}::vector`;
+            // Check if this column has chunks info and chunk querying is requested
+            const adapterData = column.adapterData;
+            const chunksInfo = adapterData?.chunksInfo;
+            if (chunksInfo && (includeChunks !== false)) {
+                // Chunk-aware query: find the closest chunk for each parent row
+                // Uses a lateral subquery to get the minimum distance across all chunks
+                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 chunkEmbedding = sql.identifier(chunksInfo.embeddingField);
+                // Use the configured PK field (defaults to 'id', but can be overridden via @hasChunks tag)
+                const parentId = sql `${alias}.${sql.identifier(chunksInfo.parentPkField)}`;
+                // Alias to avoid ambiguity when the chunks table name might collide
+                const chunksAlias = sql.identifier('__chunks');
+                // Subquery: SELECT MIN(distance) FROM chunks WHERE chunks.parent_fk = parent.pk
+                const chunkDistanceSubquery = sql `(
+          SELECT MIN(${chunksAlias}.${chunkEmbedding} ${sql.raw(operator)} ${vectorExpr})
+          FROM ${chunksTableRef} AS ${chunksAlias}
+          WHERE ${chunksAlias}.${parentFk} = ${parentId}
+        )`;
+                // Also compute direct parent distance if the parent has an embedding
+                const parentColumnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
+                const parentDistanceExpr = sql `(${parentColumnExpr} ${sql.raw(operator)} ${vectorExpr})`;
+                // 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)
+        )`;
+                let whereClause = null;
+                if (distance !== undefined && distance !== null) {
+                    whereClause = sql `${combinedDistanceExpr} <= ${sql.value(distance)}`;
+                }
+                return {
+                    whereClause,
+                    scoreExpression: combinedDistanceExpr,
+                };
+            }
+            // Standard (non-chunk) query
+            const columnExpr = sql `${alias}.${sql.identifier(column.attributeName)}`;
             const distanceExpr = sql `(${columnExpr} ${sql.raw(operator)} ${vectorExpr})`;
             let whereClause = null;
             if (distance !== undefined && distance !== null) {

package/esm/plugin.js

@@ -21,6 +21,82 @@ import 'graphile-build-pg';
 import 'graphile-connection-filter';
 import { TYPES } from '@dataplan/pg';
 import { getQueryBuilder } from 'graphile-connection-filter';
+/**
+ * Read the @searchConfig smart tag from a codec's extensions.
+ * Returns undefined if no searchConfig tag is present.
+ */
+function getSearchConfig(codec) {
+    const tags = codec.extensions?.tags;
+    if (!tags)
+        return undefined;
+    const raw = tags.searchConfig;
+    if (!raw)
+        return undefined;
+    // Smart tags can be strings (JSON-encoded) or already-parsed objects
+    if (typeof raw === 'string') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (typeof raw === 'object')
+        return raw;
+    return undefined;
+}
+/**
+ * Normalize a raw score to 0..1 using the specified strategy.
+ *
+ * When strategy is 'sigmoid', sigmoid normalization is used for ALL adapters
+ * (both bounded and unbounded). When strategy is 'linear' (default),
+ * known-range adapters use linear normalization and unbounded adapters
+ * use sigmoid normalization as fallback.
+ */
+function normalizeScore(score, lowerIsBetter, range, strategy = 'linear') {
+    let normalized;
+    if (range && strategy === 'linear') {
+        // Known range + linear strategy: linear normalization
+        const [min, max] = range;
+        normalized = lowerIsBetter
+            ? 1 - (score - min) / (max - min)
+            : (score - min) / (max - min);
+    }
+    else {
+        // Unbounded range, or explicit sigmoid strategy: sigmoid normalization
+        if (lowerIsBetter) {
+            // BM25: negative scores, more negative = better
+            normalized = 1 / (1 + Math.abs(score));
+        }
+        else {
+            // Higher-is-better: map via sigmoid
+            normalized = score / (1 + score);
+        }
+    }
+    return Math.max(0, Math.min(1, normalized));
+}
+/**
+ * Apply recency boost to a normalized score.
+ * Uses exponential decay based on age in days.
+ *
+ * @param normalizedScore - The already-normalized score (0..1)
+ * @param recencyValue - The raw recency field value (timestamp string from SQL row)
+ * @param decay - Decay factor per day (e.g. 0.95 means 5% penalty per day)
+ */
+function applyRecencyBoost(normalizedScore, recencyValue, decay) {
+    if (recencyValue == null)
+        return normalizedScore;
+    const fieldDate = new Date(recencyValue);
+    if (isNaN(fieldDate.getTime()))
+        return normalizedScore;
+    const now = new Date();
+    const ageInDays = (now.getTime() - fieldDate.getTime()) / (1000 * 60 * 60 * 24);
+    if (ageInDays < 0)
+        return normalizedScore; // future dates get no penalty
+    // Exponential decay: boost = decay^ageInDays
+    const boost = Math.pow(decay, ageInDays);
+    return normalizedScore * boost;
+}
 /**
  * Creates the unified search plugin with the given options.
  */
@@ -195,7 +271,7 @@ export function createUnifiedSearchPlugin(options) {
                  * on the appropriate output types.
                  */
                 GraphQLObjectType_fields(fields, build, context) {
-                    const { inflection, graphql: { GraphQLFloat }, grafast: { lambda }, } = build;
+                    const { inflection, sql, graphql: { GraphQLFloat }, grafast: { lambda }, } = build;
                     const { scope: { isPgClassType, pgCodec: rawPgCodec }, fieldWithHooks, } = context;
                     if (!isPgClassType || !rawPgCodec?.attributes) {
                         return fields;
@@ -266,6 +342,24 @@ export function createUnifiedSearchPlugin(options) {
                                 });
                             }
                         }
+                        // Read per-table @searchConfig smart tag (written by DataSearch/DataFullTextSearch/DataBm25)
+                        // Per-table config overrides global searchScoreWeights
+                        const tableSearchConfig = getSearchConfig(codec);
+                        // Resolve effective weights: per-table > global > equal (undefined)
+                        const effectiveWeights = tableSearchConfig?.weights ?? options.searchScoreWeights;
+                        // Resolve normalization strategy: per-table > default 'linear'
+                        const normalizationStrategy = tableSearchConfig?.normalization ?? 'linear';
+                        // Recency boost config from per-table smart tag
+                        let boostRecent = tableSearchConfig?.boost_recent ?? false;
+                        const boostRecencyField = tableSearchConfig?.boost_recency_field ?? 'updated_at';
+                        const boostRecencyDecay = tableSearchConfig?.boost_recency_decay ?? 0.95;
+                        // Phase I: Validate that the recency field actually exists on the table.
+                        // If it doesn't, disable recency boost gracefully instead of crashing at query time.
+                        if (boostRecent && boostRecencyField && !codec.attributes[boostRecencyField]) {
+                            console.warn(`[graphile-search] @searchConfig.boost_recency_field "${boostRecencyField}" ` +
+                                `not found on table "${codec.name}". Recency boost disabled for this table.`);
+                            boostRecent = false;
+                        }
                         newFields = build.extend(newFields, {
                             searchScore: fieldWithHooks({
                                 fieldName: 'searchScore',
@@ -273,6 +367,7 @@ export function createUnifiedSearchPlugin(options) {
                             }, () => ({
                                 description: 'Composite search relevance score (0..1, higher = more relevant). ' +
                                     'Computed by normalizing and averaging all active search signals. ' +
+                                    'Supports per-table weight customization via @searchConfig smart tag. ' +
                                     'Returns null when no search filters are active.',
                                 type: GraphQLFloat,
                                 plan($step) {
@@ -287,12 +382,25 @@ export function createUnifiedSearchPlugin(options) {
                                     }
                                     // Collect all meta steps for all adapters
                                     const $metaSteps = allMetaKeys.map((mk) => $select.getMeta(mk.metaKey));
+                                    // If recency boost is configured, inject the recency field into
+                                    // the SQL SELECT so we can read it by numeric index at runtime.
+                                    let recencySelectIndex = null;
+                                    if (boostRecent && boostRecencyField) {
+                                        const recencyColumnSql = sql `${$select.alias}.${sql.identifier(boostRecencyField)}::text`;
+                                        recencySelectIndex = $select.selectAndReturnIndex(recencyColumnSql);
+                                    }
+                                    // Capture the index in a local const for the lambda closure
+                                    const capturedRecencyIndex = recencySelectIndex;
                                     return lambda([...$metaSteps, $row], (args) => {
                                         const row = args[args.length - 1];
                                         if (row == null)
                                             return null;
-                                        let sum = 0;
-                                        let count = 0;
+                                        let weightedSum = 0;
+                                        let totalWeight = 0;
+                                        // Read recency value from the injected SELECT column
+                                        const recencyValue = (boostRecent && capturedRecencyIndex != null)
+                                            ? row[capturedRecencyIndex]
+                                            : null;
                                         for (let i = 0; i < allMetaKeys.length; i++) {
                                             const details = args[i];
                                             if (details == null || details.selectIndex == null)
@@ -304,74 +412,19 @@ export function createUnifiedSearchPlugin(options) {
                                             if (typeof score !== 'number' || isNaN(score))
                                                 continue;
                                             const mk = allMetaKeys[i];
-                                            // Normalize to 0..1 (higher = better)
-                                            let normalized;
-                                            if (mk.range) {
-                                                // Known range: linear normalization
-                                                const [min, max] = mk.range;
-                                                normalized = mk.lowerIsBetter
-                                                    ? 1 - (score - min) / (max - min)
-                                                    : (score - min) / (max - min);
+                                            const weight = effectiveWeights?.[mk.adapterName] ?? 1;
+                                            // Normalize using the resolved strategy
+                                            let normalized = normalizeScore(score, mk.lowerIsBetter, mk.range, normalizationStrategy);
+                                            // Apply recency boost if configured
+                                            if (boostRecent && recencyValue != null) {
+                                                normalized = applyRecencyBoost(normalized, recencyValue, boostRecencyDecay);
                                             }
-                                            else {
-                                                // Unbounded: sigmoid normalization
-                                                if (mk.lowerIsBetter) {
-                                                    // BM25: negative scores, more negative = better
-                                                    // Map via 1 / (1 + abs(score))
-                                                    normalized = 1 / (1 + Math.abs(score));
-                                                }
-                                                else {
-                                                    // Hypothetical unbounded higher-is-better
-                                                    normalized = score / (1 + score);
-                                                }
-                                            }
-                                            // Clamp to [0, 1]
-                                            normalized = Math.max(0, Math.min(1, normalized));
-                                            sum += normalized;
-                                            count++;
+                                            weightedSum += normalized * weight;
+                                            totalWeight += weight;
                                         }
-                                        if (count === 0)
+                                        if (totalWeight === 0)
                                             return null;
-                                        // Apply optional weights
-                                        if (options.searchScoreWeights) {
-                                            let weightedSum = 0;
-                                            let totalWeight = 0;
-                                            let weightIdx = 0;
-                                            for (let i = 0; i < allMetaKeys.length; i++) {
-                                                const details = args[i];
-                                                if (details == null || details.selectIndex == null)
-                                                    continue;
-                                                const rawValue = row[details.selectIndex];
-                                                if (rawValue == null)
-                                                    continue;
-                                                const mk = allMetaKeys[i];
-                                                const weight = options.searchScoreWeights[mk.adapterName] ?? 1;
-                                                const score = TYPES.float.fromPg(rawValue);
-                                                if (typeof score !== 'number' || isNaN(score))
-                                                    continue;
-                                                let normalized;
-                                                if (mk.range) {
-                                                    const [min, max] = mk.range;
-                                                    normalized = mk.lowerIsBetter
-                                                        ? 1 - (score - min) / (max - min)
-                                                        : (score - min) / (max - min);
-                                                }
-                                                else {
-                                                    if (mk.lowerIsBetter) {
-                                                        normalized = 1 / (1 + Math.abs(score));
-                                                    }
-                                                    else {
-                                                        normalized = score / (1 + score);
-                                                    }
-                                                }
-                                                normalized = Math.max(0, Math.min(1, normalized));
-                                                weightedSum += normalized * weight;
-                                                totalWeight += weight;
-                                                weightIdx++;
-                                            }
-                                            return totalWeight > 0 ? weightedSum / totalWeight : null;
-                                        }
-                                        return sum / count;
+                                        return weightedSum / totalWeight;
                                     });
                                 },
                             })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-search",
-  "version": "1.2.0",
+  "version": "1.3.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.1.4",
-    "graphile-test": "^4.5.6",
+    "graphile-connection-filter": "^1.1.5",
+    "graphile-test": "^4.5.7",
     "makage": "^0.1.10",
     "pg": "^8.20.0",
-    "pgsql-test": "^4.5.6"
+    "pgsql-test": "^4.5.7"
   },
   "peerDependencies": {
     "@dataplan/pg": "1.0.0-rc.8",
@@ -62,5 +62,5 @@
     "hybrid-search",
     "searchScore"
   ],
-  "gitHead": "9f3837555601b15e693ae0b750124fb0a8df3176"
+  "gitHead": "71058a2aa53cc20255502068b0f0615c384d93d2"
 }

package/plugin.js

@@ -24,6 +24,82 @@ require("graphile-build-pg");
 require("graphile-connection-filter");
 const pg_1 = require("@dataplan/pg");
 const graphile_connection_filter_1 = require("graphile-connection-filter");
+/**
+ * Read the @searchConfig smart tag from a codec's extensions.
+ * Returns undefined if no searchConfig tag is present.
+ */
+function getSearchConfig(codec) {
+    const tags = codec.extensions?.tags;
+    if (!tags)
+        return undefined;
+    const raw = tags.searchConfig;
+    if (!raw)
+        return undefined;
+    // Smart tags can be strings (JSON-encoded) or already-parsed objects
+    if (typeof raw === 'string') {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (typeof raw === 'object')
+        return raw;
+    return undefined;
+}
+/**
+ * Normalize a raw score to 0..1 using the specified strategy.
+ *
+ * When strategy is 'sigmoid', sigmoid normalization is used for ALL adapters
+ * (both bounded and unbounded). When strategy is 'linear' (default),
+ * known-range adapters use linear normalization and unbounded adapters
+ * use sigmoid normalization as fallback.
+ */
+function normalizeScore(score, lowerIsBetter, range, strategy = 'linear') {
+    let normalized;
+    if (range && strategy === 'linear') {
+        // Known range + linear strategy: linear normalization
+        const [min, max] = range;
+        normalized = lowerIsBetter
+            ? 1 - (score - min) / (max - min)
+            : (score - min) / (max - min);
+    }
+    else {
+        // Unbounded range, or explicit sigmoid strategy: sigmoid normalization
+        if (lowerIsBetter) {
+            // BM25: negative scores, more negative = better
+            normalized = 1 / (1 + Math.abs(score));
+        }
+        else {
+            // Higher-is-better: map via sigmoid
+            normalized = score / (1 + score);
+        }
+    }
+    return Math.max(0, Math.min(1, normalized));
+}
+/**
+ * Apply recency boost to a normalized score.
+ * Uses exponential decay based on age in days.
+ *
+ * @param normalizedScore - The already-normalized score (0..1)
+ * @param recencyValue - The raw recency field value (timestamp string from SQL row)
+ * @param decay - Decay factor per day (e.g. 0.95 means 5% penalty per day)
+ */
+function applyRecencyBoost(normalizedScore, recencyValue, decay) {
+    if (recencyValue == null)
+        return normalizedScore;
+    const fieldDate = new Date(recencyValue);
+    if (isNaN(fieldDate.getTime()))
+        return normalizedScore;
+    const now = new Date();
+    const ageInDays = (now.getTime() - fieldDate.getTime()) / (1000 * 60 * 60 * 24);
+    if (ageInDays < 0)
+        return normalizedScore; // future dates get no penalty
+    // Exponential decay: boost = decay^ageInDays
+    const boost = Math.pow(decay, ageInDays);
+    return normalizedScore * boost;
+}
 /**
  * Creates the unified search plugin with the given options.
  */
@@ -198,7 +274,7 @@ function createUnifiedSearchPlugin(options) {
                  * on the appropriate output types.
                  */
                 GraphQLObjectType_fields(fields, build, context) {
-                    const { inflection, graphql: { GraphQLFloat }, grafast: { lambda }, } = build;
+                    const { inflection, sql, graphql: { GraphQLFloat }, grafast: { lambda }, } = build;
                     const { scope: { isPgClassType, pgCodec: rawPgCodec }, fieldWithHooks, } = context;
                     if (!isPgClassType || !rawPgCodec?.attributes) {
                         return fields;
@@ -269,6 +345,24 @@ function createUnifiedSearchPlugin(options) {
                                 });
                             }
                         }
+                        // Read per-table @searchConfig smart tag (written by DataSearch/DataFullTextSearch/DataBm25)
+                        // Per-table config overrides global searchScoreWeights
+                        const tableSearchConfig = getSearchConfig(codec);
+                        // Resolve effective weights: per-table > global > equal (undefined)
+                        const effectiveWeights = tableSearchConfig?.weights ?? options.searchScoreWeights;
+                        // Resolve normalization strategy: per-table > default 'linear'
+                        const normalizationStrategy = tableSearchConfig?.normalization ?? 'linear';
+                        // Recency boost config from per-table smart tag
+                        let boostRecent = tableSearchConfig?.boost_recent ?? false;
+                        const boostRecencyField = tableSearchConfig?.boost_recency_field ?? 'updated_at';
+                        const boostRecencyDecay = tableSearchConfig?.boost_recency_decay ?? 0.95;
+                        // Phase I: Validate that the recency field actually exists on the table.
+                        // If it doesn't, disable recency boost gracefully instead of crashing at query time.
+                        if (boostRecent && boostRecencyField && !codec.attributes[boostRecencyField]) {
+                            console.warn(`[graphile-search] @searchConfig.boost_recency_field "${boostRecencyField}" ` +
+                                `not found on table "${codec.name}". Recency boost disabled for this table.`);
+                            boostRecent = false;
+                        }
                         newFields = build.extend(newFields, {
                             searchScore: fieldWithHooks({
                                 fieldName: 'searchScore',
@@ -276,6 +370,7 @@ function createUnifiedSearchPlugin(options) {
                             }, () => ({
                                 description: 'Composite search relevance score (0..1, higher = more relevant). ' +
                                     'Computed by normalizing and averaging all active search signals. ' +
+                                    'Supports per-table weight customization via @searchConfig smart tag. ' +
                                     'Returns null when no search filters are active.',
                                 type: GraphQLFloat,
                                 plan($step) {
@@ -290,12 +385,25 @@ function createUnifiedSearchPlugin(options) {
                                     }
                                     // Collect all meta steps for all adapters
                                     const $metaSteps = allMetaKeys.map((mk) => $select.getMeta(mk.metaKey));
+                                    // If recency boost is configured, inject the recency field into
+                                    // the SQL SELECT so we can read it by numeric index at runtime.
+                                    let recencySelectIndex = null;
+                                    if (boostRecent && boostRecencyField) {
+                                        const recencyColumnSql = sql `${$select.alias}.${sql.identifier(boostRecencyField)}::text`;
+                                        recencySelectIndex = $select.selectAndReturnIndex(recencyColumnSql);
+                                    }
+                                    // Capture the index in a local const for the lambda closure
+                                    const capturedRecencyIndex = recencySelectIndex;
                                     return lambda([...$metaSteps, $row], (args) => {
                                         const row = args[args.length - 1];
                                         if (row == null)
                                             return null;
-                                        let sum = 0;
-                                        let count = 0;
+                                        let weightedSum = 0;
+                                        let totalWeight = 0;
+                                        // Read recency value from the injected SELECT column
+                                        const recencyValue = (boostRecent && capturedRecencyIndex != null)
+                                            ? row[capturedRecencyIndex]
+                                            : null;
                                         for (let i = 0; i < allMetaKeys.length; i++) {
                                             const details = args[i];
                                             if (details == null || details.selectIndex == null)
@@ -307,74 +415,19 @@ function createUnifiedSearchPlugin(options) {
                                             if (typeof score !== 'number' || isNaN(score))
                                                 continue;
                                             const mk = allMetaKeys[i];
-                                            // Normalize to 0..1 (higher = better)
-                                            let normalized;
-                                            if (mk.range) {
-                                                // Known range: linear normalization
-                                                const [min, max] = mk.range;
-                                                normalized = mk.lowerIsBetter
-                                                    ? 1 - (score - min) / (max - min)
-                                                    : (score - min) / (max - min);
+                                            const weight = effectiveWeights?.[mk.adapterName] ?? 1;
+                                            // Normalize using the resolved strategy
+                                            let normalized = normalizeScore(score, mk.lowerIsBetter, mk.range, normalizationStrategy);
+                                            // Apply recency boost if configured
+                                            if (boostRecent && recencyValue != null) {
+                                                normalized = applyRecencyBoost(normalized, recencyValue, boostRecencyDecay);
                                             }
-                                            else {
-                                                // Unbounded: sigmoid normalization
-                                                if (mk.lowerIsBetter) {
-                                                    // BM25: negative scores, more negative = better
-                                                    // Map via 1 / (1 + abs(score))
-                                                    normalized = 1 / (1 + Math.abs(score));
-                                                }
-                                                else {
-                                                    // Hypothetical unbounded higher-is-better
-                                                    normalized = score / (1 + score);
-                                                }
-                                            }
-                                            // Clamp to [0, 1]
-                                            normalized = Math.max(0, Math.min(1, normalized));
-                                            sum += normalized;
-                                            count++;
+                                            weightedSum += normalized * weight;
+                                            totalWeight += weight;
                                         }
-                                        if (count === 0)
+                                        if (totalWeight === 0)
                                             return null;
-                                        // Apply optional weights
-                                        if (options.searchScoreWeights) {
-                                            let weightedSum = 0;
-                                            let totalWeight = 0;
-                                            let weightIdx = 0;
-                                            for (let i = 0; i < allMetaKeys.length; i++) {
-                                                const details = args[i];
-                                                if (details == null || details.selectIndex == null)
-                                                    continue;
-                                                const rawValue = row[details.selectIndex];
-                                                if (rawValue == null)
-                                                    continue;
-                                                const mk = allMetaKeys[i];
-                                                const weight = options.searchScoreWeights[mk.adapterName] ?? 1;
-                                                const score = pg_1.TYPES.float.fromPg(rawValue);
-                                                if (typeof score !== 'number' || isNaN(score))
-                                                    continue;
-                                                let normalized;
-                                                if (mk.range) {
-                                                    const [min, max] = mk.range;
-                                                    normalized = mk.lowerIsBetter
-                                                        ? 1 - (score - min) / (max - min)
-                                                        : (score - min) / (max - min);
-                                                }
-                                                else {
-                                                    if (mk.lowerIsBetter) {
-                                                        normalized = 1 / (1 + Math.abs(score));
-                                                    }
-                                                    else {
-                                                        normalized = score / (1 + score);
-                                                    }
-                                                }
-                                                normalized = Math.max(0, Math.min(1, normalized));
-                                                weightedSum += normalized * weight;
-                                                totalWeight += weight;
-                                                weightIdx++;
-                                            }
-                                            return totalWeight > 0 ? weightedSum / totalWeight : null;
-                                        }
-                                        return sum / count;
+                                        return weightedSum / totalWeight;
                                     });
                                 },
                             })),