graphile-search 1.1.1 → 1.1.2

package/README.md

@@ -1,5 +1,17 @@
 # graphile-search
 
+<p align="center" width="100%">
+  <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
+</p>
+
+<p align="center" width="100%">
+  <a href="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml">
+    <img height="20" src="https://github.com/constructive-io/constructive/actions/workflows/run-tests.yaml/badge.svg" />
+  </a>
+   <a href="https://github.com/constructive-io/constructive/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
+   <a href="https://www.npmjs.com/package/graphile-search"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/constructive?filename=graphile%2Fgraphile-search%2Fpackage.json"/></a>
+</p>
+
 Unified PostGraphile v5 search plugin — abstracts tsvector, BM25, pg_trgm, and pgvector behind a single adapter-based architecture with composite `searchScore`.
 
 ## Overview

package/adapters/pgvector.js

@@ -29,6 +29,9 @@ function createPgvectorAdapter(options = {}) {
             range: null, // 0 to infinity
         },
         filterPrefix,
+        // pgvector operates on embedding vectors, not text search — its presence
+        // alone should NOT trigger supplementary adapters like trgm.
+        isIntentionalSearch: false,
         supportsTextSearch: false,
         // pgvector requires a vector array, not plain text — no buildTextSearchInput
         detectColumns(codec, _build) {

package/adapters/trgm.d.ts

@@ -16,5 +16,18 @@ export interface TrgmAdapterOptions {
      * @default 0.3
      */
     defaultThreshold?: number;
+    /**
+     * When true, trgm only activates on tables that have an "intentional"
+     * search column detected by another adapter (e.g. a tsvector column or
+     * a BM25 index). This prevents trgm similarity fields from being added
+     * to every table with text columns.
+     *
+     * The plugin's `getAdapterColumns` orchestrates this by running
+     * non-supplementary adapters first, then only running supplementary
+     * adapters on codecs that already have search columns.
+     *
+     * @default true
+     */
+    requireIntentionalSearch?: boolean;
 }
 export declare function createTrgmAdapter(options?: TrgmAdapterOptions): SearchAdapter;

package/adapters/trgm.js

@@ -12,9 +12,14 @@ function isTextCodec(codec) {
     return name === 'text' || name === 'varchar' || name === 'bpchar';
 }
 function createTrgmAdapter(options = {}) {
-    const { filterPrefix = 'trgm', defaultThreshold = 0.3 } = options;
+    const { filterPrefix = 'trgm', defaultThreshold = 0.3, requireIntentionalSearch = true, } = options;
     return {
         name: 'trgm',
+        /**
+         * When true, this adapter is "supplementary" — it only activates on
+         * tables that already have columns detected by a non-supplementary adapter.
+         */
+        isSupplementary: requireIntentionalSearch,
         scoreSemantics: {
             metric: 'similarity',
             lowerIsBetter: false,

package/esm/adapters/pgvector.js

@@ -26,6 +26,9 @@ export function createPgvectorAdapter(options = {}) {
             range: null, // 0 to infinity
         },
         filterPrefix,
+        // pgvector operates on embedding vectors, not text search — its presence
+        // alone should NOT trigger supplementary adapters like trgm.
+        isIntentionalSearch: false,
         supportsTextSearch: false,
         // pgvector requires a vector array, not plain text — no buildTextSearchInput
         detectColumns(codec, _build) {

package/esm/adapters/trgm.d.ts

@@ -16,5 +16,18 @@ export interface TrgmAdapterOptions {
      * @default 0.3
      */
     defaultThreshold?: number;
+    /**
+     * When true, trgm only activates on tables that have an "intentional"
+     * search column detected by another adapter (e.g. a tsvector column or
+     * a BM25 index). This prevents trgm similarity fields from being added
+     * to every table with text columns.
+     *
+     * The plugin's `getAdapterColumns` orchestrates this by running
+     * non-supplementary adapters first, then only running supplementary
+     * adapters on codecs that already have search columns.
+     *
+     * @default true
+     */
+    requireIntentionalSearch?: boolean;
 }
 export declare function createTrgmAdapter(options?: TrgmAdapterOptions): SearchAdapter;

package/esm/adapters/trgm.js

@@ -9,9 +9,14 @@ function isTextCodec(codec) {
     return name === 'text' || name === 'varchar' || name === 'bpchar';
 }
 export function createTrgmAdapter(options = {}) {
-    const { filterPrefix = 'trgm', defaultThreshold = 0.3 } = options;
+    const { filterPrefix = 'trgm', defaultThreshold = 0.3, requireIntentionalSearch = true, } = options;
     return {
         name: 'trgm',
+        /**
+         * When true, this adapter is "supplementary" — it only activates on
+         * tables that already have columns detected by a non-supplementary adapter.
+         */
+        isSupplementary: requireIntentionalSearch,
         scoreSemantics: {
             metric: 'similarity',
             lowerIsBetter: false,

package/esm/plugin.js

@@ -30,17 +30,46 @@ export function createUnifiedSearchPlugin(options) {
     const codecCache = new Map();
     /**
      * Get (or compute) the adapter columns for a given codec.
+     *
+     * Runs non-supplementary adapters first (e.g. tsvector, BM25, pgvector).
+     * Supplementary adapters (e.g. trgm with requireIntentionalSearch) are only
+     * run if at least one adapter with `isIntentionalSearch: true` found columns.
+     *
+     * This distinction matters because pgvector (embeddings) is NOT intentional
+     * text search — its presence alone should not trigger trgm similarity fields.
+     * Only tsvector and BM25, which represent explicit search infrastructure,
+     * count as intentional search.
      */
     function getAdapterColumns(codec, build) {
         const cacheKey = codec.name;
         if (codecCache.has(cacheKey)) {
             return codecCache.get(cacheKey);
         }
+        const primaryAdapters = adapters.filter((a) => !a.isSupplementary);
+        const supplementaryAdapters = adapters.filter((a) => a.isSupplementary);
+        // Phase 1: Run non-supplementary adapters (tsvector, BM25, pgvector, etc.)
         const results = [];
-        for (const adapter of adapters) {
+        let hasIntentionalSearch = false;
+        for (const adapter of primaryAdapters) {
             const columns = adapter.detectColumns(codec, build);
             if (columns.length > 0) {
                 results.push({ adapter, columns });
+                // Track whether any "intentional search" adapter found columns.
+                // isIntentionalSearch defaults to true when not explicitly set.
+                if (adapter.isIntentionalSearch !== false) {
+                    hasIntentionalSearch = true;
+                }
+            }
+        }
+        // Phase 2: Only run supplementary adapters if at least one primary
+        // adapter with isIntentionalSearch found columns on this codec.
+        // pgvector (isIntentionalSearch: false) alone won't trigger trgm.
+        if (hasIntentionalSearch) {
+            for (const adapter of supplementaryAdapters) {
+                const columns = adapter.detectColumns(codec, build);
+                if (columns.length > 0) {
+                    results.push({ adapter, columns });
+                }
             }
         }
         codecCache.set(cacheKey, results);
@@ -105,9 +134,12 @@ export function createUnifiedSearchPlugin(options) {
                         provides: ['default'],
                         before: ['inferred', 'override', 'PgAttributesPlugin'],
                         callback(behavior, [codec, attributeName], build) {
-                            // Check if any adapter claims this column
-                            for (const adapter of adapters) {
-                                const columns = adapter.detectColumns(codec, build);
+                            // Use getAdapterColumns which respects isSupplementary logic,
+                            // so trgm columns only appear when intentional search exists
+                            if (!codec?.attributes)
+                                return behavior;
+                            const adapterColumns = getAdapterColumns(codec, build);
+                            for (const { columns } of adapterColumns) {
                                 if (columns.some((c) => c.attributeName === attributeName)) {
                                     return [
                                         'unifiedSearch:orderBy',

package/esm/types.d.ts

@@ -64,6 +64,33 @@ export interface SearchAdapter {
     name: string;
     /** Score semantics for this algorithm. */
     scoreSemantics: ScoreSemantics;
+    /**
+     * When true, this adapter is "supplementary" — it only activates on
+     * tables that already have at least one column detected by an adapter
+     * whose `isIntentionalSearch` is true (e.g. tsvector or BM25).
+     *
+     * This prevents adapters like pg_trgm from adding similarity fields
+     * to every table with text columns when there is no intentional search setup.
+     *
+     * pgvector (embeddings) does NOT count as intentional search because it
+     * operates on vector columns, not text search — so its presence alone
+     * won't trigger supplementary adapters.
+     *
+     * @default false
+     */
+    isSupplementary?: boolean;
+    /**
+     * When true, this adapter represents "intentional search" — its presence
+     * on a table signals that the table was explicitly set up for search and
+     * should trigger supplementary adapters (e.g. trgm).
+     *
+     * Adapters that check for real infrastructure (tsvector columns, BM25
+     * indexes) should set this to true. Adapters that operate on a different
+     * domain (pgvector embeddings) should set this to false.
+     *
+     * @default true
+     */
+    isIntentionalSearch?: boolean;
     /**
      * The filter prefix used for filter field names on the connection filter input.
      * The field name is: `{filterPrefix}{ColumnName}` (camelCase).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-search",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "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.1",
-    "graphile-test": "^4.5.3",
+    "graphile-connection-filter": "^1.1.2",
+    "graphile-test": "^4.5.4",
     "makage": "^0.1.10",
     "pg": "^8.20.0",
-    "pgsql-test": "^4.5.3"
+    "pgsql-test": "^4.5.4"
   },
   "peerDependencies": {
     "@dataplan/pg": "1.0.0-rc.8",
@@ -62,5 +62,5 @@
     "hybrid-search",
     "searchScore"
   ],
-  "gitHead": "21fd7c2c30663548cf15aa448c1935ab56e5497d"
+  "gitHead": "8afe6b19da82facbe5f3365762ba52888af5b3c9"
 }

package/plugin.js

@@ -33,17 +33,46 @@ function createUnifiedSearchPlugin(options) {
     const codecCache = new Map();
     /**
      * Get (or compute) the adapter columns for a given codec.
+     *
+     * Runs non-supplementary adapters first (e.g. tsvector, BM25, pgvector).
+     * Supplementary adapters (e.g. trgm with requireIntentionalSearch) are only
+     * run if at least one adapter with `isIntentionalSearch: true` found columns.
+     *
+     * This distinction matters because pgvector (embeddings) is NOT intentional
+     * text search — its presence alone should not trigger trgm similarity fields.
+     * Only tsvector and BM25, which represent explicit search infrastructure,
+     * count as intentional search.
      */
     function getAdapterColumns(codec, build) {
         const cacheKey = codec.name;
         if (codecCache.has(cacheKey)) {
             return codecCache.get(cacheKey);
         }
+        const primaryAdapters = adapters.filter((a) => !a.isSupplementary);
+        const supplementaryAdapters = adapters.filter((a) => a.isSupplementary);
+        // Phase 1: Run non-supplementary adapters (tsvector, BM25, pgvector, etc.)
         const results = [];
-        for (const adapter of adapters) {
+        let hasIntentionalSearch = false;
+        for (const adapter of primaryAdapters) {
             const columns = adapter.detectColumns(codec, build);
             if (columns.length > 0) {
                 results.push({ adapter, columns });
+                // Track whether any "intentional search" adapter found columns.
+                // isIntentionalSearch defaults to true when not explicitly set.
+                if (adapter.isIntentionalSearch !== false) {
+                    hasIntentionalSearch = true;
+                }
+            }
+        }
+        // Phase 2: Only run supplementary adapters if at least one primary
+        // adapter with isIntentionalSearch found columns on this codec.
+        // pgvector (isIntentionalSearch: false) alone won't trigger trgm.
+        if (hasIntentionalSearch) {
+            for (const adapter of supplementaryAdapters) {
+                const columns = adapter.detectColumns(codec, build);
+                if (columns.length > 0) {
+                    results.push({ adapter, columns });
+                }
             }
         }
         codecCache.set(cacheKey, results);
@@ -108,9 +137,12 @@ function createUnifiedSearchPlugin(options) {
                         provides: ['default'],
                         before: ['inferred', 'override', 'PgAttributesPlugin'],
                         callback(behavior, [codec, attributeName], build) {
-                            // Check if any adapter claims this column
-                            for (const adapter of adapters) {
-                                const columns = adapter.detectColumns(codec, build);
+                            // Use getAdapterColumns which respects isSupplementary logic,
+                            // so trgm columns only appear when intentional search exists
+                            if (!codec?.attributes)
+                                return behavior;
+                            const adapterColumns = getAdapterColumns(codec, build);
+                            for (const { columns } of adapterColumns) {
                                 if (columns.some((c) => c.attributeName === attributeName)) {
                                     return [
                                         'unifiedSearch:orderBy',

package/types.d.ts

@@ -64,6 +64,33 @@ export interface SearchAdapter {
     name: string;
     /** Score semantics for this algorithm. */
     scoreSemantics: ScoreSemantics;
+    /**
+     * When true, this adapter is "supplementary" — it only activates on
+     * tables that already have at least one column detected by an adapter
+     * whose `isIntentionalSearch` is true (e.g. tsvector or BM25).
+     *
+     * This prevents adapters like pg_trgm from adding similarity fields
+     * to every table with text columns when there is no intentional search setup.
+     *
+     * pgvector (embeddings) does NOT count as intentional search because it
+     * operates on vector columns, not text search — so its presence alone
+     * won't trigger supplementary adapters.
+     *
+     * @default false
+     */
+    isSupplementary?: boolean;
+    /**
+     * When true, this adapter represents "intentional search" — its presence
+     * on a table signals that the table was explicitly set up for search and
+     * should trigger supplementary adapters (e.g. trgm).
+     *
+     * Adapters that check for real infrastructure (tsvector columns, BM25
+     * indexes) should set this to true. Adapters that operate on a different
+     * domain (pgvector embeddings) should set this to false.
+     *
+     * @default true
+     */
+    isIntentionalSearch?: boolean;
     /**
      * The filter prefix used for filter field names on the connection filter input.
      * The field name is: `{filterPrefix}{ColumnName}` (camelCase).