graphile-search 1.1.0 → 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/adapters/tsvector.js

@@ -8,8 +8,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTsvectorAdapter = createTsvectorAdapter;
 function isTsvectorCodec(codec) {
-    return (codec?.extensions?.pg?.schemaName === 'pg_catalog' &&
-        codec?.extensions?.pg?.name === 'tsvector');
+    // 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
+    // match both the built-in codec and our custom codec (for older versions).
+    return (codec?.name === 'tsvector' ||
+        (codec?.extensions?.pg?.schemaName === 'pg_catalog' &&
+            codec?.extensions?.pg?.name === 'tsvector'));
 }
 function createTsvectorAdapter(options = {}) {
     const { filterPrefix = 'tsv', tsConfig = 'english' } = options;

package/codecs/tsvector-codec.d.ts

@@ -2,15 +2,20 @@
  * TsvectorCodecPlugin
  *
  * Teaches PostGraphile v5 how to handle PostgreSQL's tsvector and tsquery types.
- * Without this, tsvector columns are invisible to the schema builder and the
- * search plugin cannot generate condition fields.
  *
- * This plugin:
+ * In graphile-build-pg >= 5.0.0-rc.8, tsvector/tsquery codecs are handled
+ * natively and tsvector columns are HIDDEN by default (PgAttributesPlugin
+ * HIDE_BY_DEFAULT). This plugin:
+ *
  * 1. Creates codecs for tsvector/tsquery via gather.hooks.pgCodecs_findPgCodec
+ *    (kept for backward compatibility with older versions; rc.8+ handles this
+ *    natively so the hook returns early when event.pgCodec is already set)
  * 2. Registers a custom "FullText" scalar type for tsvector columns
  * 3. Maps tsvector codec to the FullText scalar (isolating filter operators)
  * 4. Maps tsquery codec to GraphQL String
- * 5. Optionally hides tsvector columns from output types
+ * 5. Re-enables tsvector columns for select/filterBy so that search plugins
+ *    can detect and use them (overrides rc.8's HIDE_BY_DEFAULT)
+ * 6. Optionally hides tsvector columns from output types
  */
 import type { GraphileConfig } from 'graphile-config';
 /**

package/codecs/tsvector-codec.js

@@ -3,15 +3,20 @@
  * TsvectorCodecPlugin
  *
  * Teaches PostGraphile v5 how to handle PostgreSQL's tsvector and tsquery types.
- * Without this, tsvector columns are invisible to the schema builder and the
- * search plugin cannot generate condition fields.
  *
- * This plugin:
+ * In graphile-build-pg >= 5.0.0-rc.8, tsvector/tsquery codecs are handled
+ * natively and tsvector columns are HIDDEN by default (PgAttributesPlugin
+ * HIDE_BY_DEFAULT). This plugin:
+ *
  * 1. Creates codecs for tsvector/tsquery via gather.hooks.pgCodecs_findPgCodec
+ *    (kept for backward compatibility with older versions; rc.8+ handles this
+ *    natively so the hook returns early when event.pgCodec is already set)
  * 2. Registers a custom "FullText" scalar type for tsvector columns
  * 3. Maps tsvector codec to the FullText scalar (isolating filter operators)
  * 4. Maps tsquery codec to GraphQL String
- * 5. Optionally hides tsvector columns from output types
+ * 5. Re-enables tsvector columns for select/filterBy so that search plugins
+ *    can detect and use them (overrides rc.8's HIDE_BY_DEFAULT)
+ * 6. Optionally hides tsvector columns from output types
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -130,25 +135,41 @@ function createTsvectorCodecPlugin(options = {}) {
                     },
                 },
             },
-            ...(hideTsvectorColumns
-                ? {
-                    entityBehavior: {
-                        pgCodecAttribute: {
-                            inferred: {
-                                after: ['postInferred'],
-                                provides: ['hideTsvectorColumns'],
-                                callback(behavior, [codec, attributeName]) {
-                                    const attr = codec.attributes?.[attributeName];
-                                    if (attr?.codec?.name === 'tsvector') {
-                                        return [behavior, '-select'];
-                                    }
-                                    return behavior;
-                                },
-                            },
+            // In graphile-build-pg >= 5.0.0-rc.8, PgAttributesPlugin HIDE_BY_DEFAULT
+            // hides tsvector columns entirely (-attribute:select, -attribute:base,
+            // -condition:attribute:filterBy, etc.). We need entity behavior to
+            // re-enable them so search plugins can detect and use them.
+            entityBehavior: {
+                pgCodecAttribute: {
+                    inferred: {
+                        after: ['default'],
+                        provides: ['tsvectorCodecPlugin'],
+                        callback(behavior, [codec, attributeName]) {
+                            const attr = codec.attributes?.[attributeName];
+                            const attrCodec = attr?.codec;
+                            const isTsvector = attrCodec?.name === 'tsvector' ||
+                                (attrCodec?.extensions?.pg?.schemaName === 'pg_catalog' &&
+                                    attrCodec?.extensions?.pg?.name === 'tsvector');
+                            if (!isTsvector) {
+                                return behavior;
+                            }
+                            if (hideTsvectorColumns) {
+                                // User explicitly wants tsvector columns hidden from output
+                                return [behavior, '-attribute:select'];
+                            }
+                            // Re-enable tsvector columns that rc.8 hides by default.
+                            // The search plugin needs attribute:select to detect columns,
+                            // and condition:attribute:filterBy for standard filter support.
+                            return [
+                                behavior,
+                                'attribute:select',
+                                'attribute:base',
+                                'condition:attribute:filterBy',
+                            ];
                         },
                     },
-                }
-                : {}),
+                },
+            },
         },
     };
 }

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/adapters/tsvector.js

@@ -5,8 +5,12 @@
  * Wraps the same SQL logic as graphile-tsvector but as a SearchAdapter.
  */
 function isTsvectorCodec(codec) {
-    return (codec?.extensions?.pg?.schemaName === 'pg_catalog' &&
-        codec?.extensions?.pg?.name === 'tsvector');
+    // 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
+    // match both the built-in codec and our custom codec (for older versions).
+    return (codec?.name === 'tsvector' ||
+        (codec?.extensions?.pg?.schemaName === 'pg_catalog' &&
+            codec?.extensions?.pg?.name === 'tsvector'));
 }
 export function createTsvectorAdapter(options = {}) {
     const { filterPrefix = 'tsv', tsConfig = 'english' } = options;

package/esm/codecs/tsvector-codec.d.ts

@@ -2,15 +2,20 @@
  * TsvectorCodecPlugin
  *
  * Teaches PostGraphile v5 how to handle PostgreSQL's tsvector and tsquery types.
- * Without this, tsvector columns are invisible to the schema builder and the
- * search plugin cannot generate condition fields.
  *
- * This plugin:
+ * In graphile-build-pg >= 5.0.0-rc.8, tsvector/tsquery codecs are handled
+ * natively and tsvector columns are HIDDEN by default (PgAttributesPlugin
+ * HIDE_BY_DEFAULT). This plugin:
+ *
  * 1. Creates codecs for tsvector/tsquery via gather.hooks.pgCodecs_findPgCodec
+ *    (kept for backward compatibility with older versions; rc.8+ handles this
+ *    natively so the hook returns early when event.pgCodec is already set)
  * 2. Registers a custom "FullText" scalar type for tsvector columns
  * 3. Maps tsvector codec to the FullText scalar (isolating filter operators)
  * 4. Maps tsquery codec to GraphQL String
- * 5. Optionally hides tsvector columns from output types
+ * 5. Re-enables tsvector columns for select/filterBy so that search plugins
+ *    can detect and use them (overrides rc.8's HIDE_BY_DEFAULT)
+ * 6. Optionally hides tsvector columns from output types
  */
 import type { GraphileConfig } from 'graphile-config';
 /**

package/esm/codecs/tsvector-codec.js

@@ -2,15 +2,20 @@
  * TsvectorCodecPlugin
  *
  * Teaches PostGraphile v5 how to handle PostgreSQL's tsvector and tsquery types.
- * Without this, tsvector columns are invisible to the schema builder and the
- * search plugin cannot generate condition fields.
  *
- * This plugin:
+ * In graphile-build-pg >= 5.0.0-rc.8, tsvector/tsquery codecs are handled
+ * natively and tsvector columns are HIDDEN by default (PgAttributesPlugin
+ * HIDE_BY_DEFAULT). This plugin:
+ *
  * 1. Creates codecs for tsvector/tsquery via gather.hooks.pgCodecs_findPgCodec
+ *    (kept for backward compatibility with older versions; rc.8+ handles this
+ *    natively so the hook returns early when event.pgCodec is already set)
  * 2. Registers a custom "FullText" scalar type for tsvector columns
  * 3. Maps tsvector codec to the FullText scalar (isolating filter operators)
  * 4. Maps tsquery codec to GraphQL String
- * 5. Optionally hides tsvector columns from output types
+ * 5. Re-enables tsvector columns for select/filterBy so that search plugins
+ *    can detect and use them (overrides rc.8's HIDE_BY_DEFAULT)
+ * 6. Optionally hides tsvector columns from output types
  */
 import { GraphQLString } from 'graphql';
 import sql from 'pg-sql2';
@@ -123,25 +128,41 @@ export function createTsvectorCodecPlugin(options = {}) {
                     },
                 },
             },
-            ...(hideTsvectorColumns
-                ? {
-                    entityBehavior: {
-                        pgCodecAttribute: {
-                            inferred: {
-                                after: ['postInferred'],
-                                provides: ['hideTsvectorColumns'],
-                                callback(behavior, [codec, attributeName]) {
-                                    const attr = codec.attributes?.[attributeName];
-                                    if (attr?.codec?.name === 'tsvector') {
-                                        return [behavior, '-select'];
-                                    }
-                                    return behavior;
-                                },
-                            },
+            // In graphile-build-pg >= 5.0.0-rc.8, PgAttributesPlugin HIDE_BY_DEFAULT
+            // hides tsvector columns entirely (-attribute:select, -attribute:base,
+            // -condition:attribute:filterBy, etc.). We need entity behavior to
+            // re-enable them so search plugins can detect and use them.
+            entityBehavior: {
+                pgCodecAttribute: {
+                    inferred: {
+                        after: ['default'],
+                        provides: ['tsvectorCodecPlugin'],
+                        callback(behavior, [codec, attributeName]) {
+                            const attr = codec.attributes?.[attributeName];
+                            const attrCodec = attr?.codec;
+                            const isTsvector = attrCodec?.name === 'tsvector' ||
+                                (attrCodec?.extensions?.pg?.schemaName === 'pg_catalog' &&
+                                    attrCodec?.extensions?.pg?.name === 'tsvector');
+                            if (!isTsvector) {
+                                return behavior;
+                            }
+                            if (hideTsvectorColumns) {
+                                // User explicitly wants tsvector columns hidden from output
+                                return [behavior, '-attribute:select'];
+                            }
+                            // Re-enable tsvector columns that rc.8 hides by default.
+                            // The search plugin needs attribute:select to detect columns,
+                            // and condition:attribute:filterBy for standard filter support.
+                            return [
+                                behavior,
+                                'attribute:select',
+                                'attribute:base',
+                                'condition:attribute:filterBy',
+                            ];
                         },
                     },
-                }
-                : {}),
+                },
+            },
         },
     };
 }

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.0",
+  "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,20 +31,20 @@
   "devDependencies": {
     "@types/node": "^22.19.11",
     "@types/pg": "^8.18.0",
-    "graphile-connection-filter": "^1.1.0",
-    "graphile-test": "^4.5.2",
+    "graphile-connection-filter": "^1.1.2",
+    "graphile-test": "^4.5.4",
     "makage": "^0.1.10",
-    "pg": "^8.19.0",
-    "pgsql-test": "^4.5.2"
+    "pg": "^8.20.0",
+    "pgsql-test": "^4.5.4"
   },
   "peerDependencies": {
-    "@dataplan/pg": "1.0.0-rc.5",
-    "graphile-build": "5.0.0-rc.4",
-    "graphile-build-pg": "5.0.0-rc.5",
-    "graphile-config": "1.0.0-rc.5",
-    "graphql": "^16.9.0",
-    "pg-sql2": "5.0.0-rc.4",
-    "postgraphile": "5.0.0-rc.7"
+    "@dataplan/pg": "1.0.0-rc.8",
+    "graphile-build": "5.0.0-rc.6",
+    "graphile-build-pg": "5.0.0-rc.8",
+    "graphile-config": "1.0.0-rc.6",
+    "graphql": "16.13.0",
+    "pg-sql2": "5.0.0-rc.5",
+    "postgraphile": "5.0.0-rc.10"
   },
   "keywords": [
     "postgraphile",
@@ -62,5 +62,5 @@
     "hybrid-search",
     "searchScore"
   ],
-  "gitHead": "1ade5f10df8e38a5f87bbd2e2f7ec2ba97267079"
+  "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).