feat: consolidate search into graphile-search + rename filter arg to where

[pyramation]

feat: consolidate search into graphile-search + rename filter arg to where

Summary

Two major changes in this PR:

1. Unified Search Plugin — Package Consolidation

Consolidates 4 individual search packages (graphile-tsvector, graphile-bm25, graphile-trgm, graphile-pgvector) into the single graphile-search package. All 4 packages are deleted with no deprecation — codec plugins, operator factories, and adapters now live inside graphile-search with tree-shakable exports.

2. Configurable connectionFilterArgumentName (default: 'where')

Renames the GraphQL connection filter argument from filter to where by default. The argument name is configurable via the connectionFilterArgumentName schema option. Since the GraphQL argument now defaults to where (matching the SDK's where parameter), the codegen translation layer (argName: 'filter') is removed — no more SDK↔GraphQL mismatch.

What changed for the where rename:

• graphile-connection-filter/src/types.ts — Added connectionFilterArgumentName?: string to ConnectionFilterOptions
• graphile-connection-filter/src/augmentations.ts — Added option to SchemaOptions interface
• graphile-connection-filter/src/plugins/ConnectionFilterArgPlugin.ts — Reads option with 'where' default, uses dynamic arg name
• graphile-connection-filter/src/preset.ts — Default set to connectionFilterArgumentName: 'where'
• graphql/codegen/.../query-builder.ts — Removed argName: 'filter' from 2 addVariable calls (lines ~248, ~364)
• graphql/query/src/ast.ts — Changed variable name from filter to where
• graphql/query/src/generators/select.ts — Changed argument from 'filter' to 'where'
• functions/send-email-link/src/index.ts — Updated 3 hardcoded GraphQL queries from condition:/filter: to where: with proper filter syntax (e.g. { id: { equalTo: $id } })
• jobs/knative-job-service/__tests__/jobs.e2e.test.ts — Updated jobByIdQuery from filter: to where:
• All test files — Bulk renamed filter: → where: in GraphQL query strings (5 test files)
• All snapshots — Regenerated locally (codegen, query) or restored + updated (server-test, graphql/test) to reflect where argument name
• graphile-settings/__tests__/preset-integration.test.ts — Fixed assertion: toContain('filter') → toContain('where')

What was deleted (search consolidation)

• graphile/graphile-tsvector/ — entire package
• graphile/graphile-bm25/ — entire package
• graphile/graphile-trgm/ — entire package
• graphile/graphile-pgvector/ — entire package
• CI test jobs for graphile-search-plugin and graphile-pgvector-plugin

What was moved into graphile-search/

• src/codecs/tsvector-codec.ts — tsvector/tsquery type registration (from graphile-tsvector)
• src/codecs/bm25-codec.ts — BM25 index discovery + codec (from graphile-bm25)
• src/codecs/vector-codec.ts — pgvector type registration (from graphile-pgvector)
• src/codecs/operator-factories.ts — createMatchesOperatorFactory + createTrgmOperatorFactories (from graphile-tsvector/graphile-trgm)
• src/codecs/index.ts — barrel re-exports

Architecture (unchanged from v1)

┌─────────────────────────────────────┐
│      createUnifiedSearchPlugin      │
│   (iterates adapters, wires hooks)  │
├─────────────────────────────────────┤
│ tsvectorAdapter │ bm25Adapter       │
│ trgmAdapter     │ pgvectorAdapter   │
├─────────────────────────────────────┤
│           src/codecs/               │
│  tsvector-codec │ bm25-codec        │
│  vector-codec   │ operator-factories│
└─────────────────────────────────────┘

Tree-shakable imports

// Full preset (includes codecs + adapters + operator factories)
import { UnifiedSearchPreset } from 'graphile-search';

// Individual codecs (tree-shakable)
import { TsvectorCodecPlugin, Bm25CodecPlugin, VectorCodecPlugin } from 'graphile-search';

// Operator factories for connection filter integration
import { createMatchesOperatorFactory, createTrgmOperatorFactories } from 'graphile-search';

Generated GraphQL fields (unchanged from v1)

• Filter inputs: {algorithm}{Column} (e.g. bm25Body, trgmTitle, vectorEmbedding)
• Composite filter: fullTextSearch: String — fans out to all text-compatible adapters
• Score fields: {column}{Algorithm}{Metric} (e.g. bodyBm25Score, titleTrgmSimilarity)
• OrderBy enums: {COLUMN}_{ALGORITHM}_{METRIC}_ASC/DESC + SEARCH_SCORE_ASC/DESC
• Composite searchScore: Normalized 0..1 aggregating all active search signals

---

Updates since last revision

Fixed knative-job-service CI failures — The filter → where rename broke 2 locations that had hardcoded GraphQL queries:

1. functions/send-email-link/src/index.ts — 3 queries (GetUser, GetDatabaseInfo, siteModules) were using condition: or filter: and needed to be updated to where: with proper filter syntax (e.g. condition: { id: $userId } → where: { id: { equalTo: $userId } })
2. jobs/knative-job-service/__tests__/jobs.e2e.test.ts — The jobByIdQuery used filter: and needed to be updated to where:

The knative test was failing because the send-email-link function would make GraphQL queries with filter: (which returned HTTP 400), causing the job to fail before it could call the simple-email function. This cascaded into the "Missing required field 'subject'" error because the email subject was never generated.

CI is now fully green — 42/42 passing (previously reported 41/41 with knative failing).

---

Review & Testing Checklist for Human

• Verify where argument rename is acceptable — This is a breaking change for existing GraphQL clients. Clients using filter: will need to update to where: or configure connectionFilterArgumentName: 'filter' to maintain backward compatibility
• Check for other hardcoded GraphQL queries — The send-email-link function had hardcoded queries that broke. Are there other deployed services or scripts with similar hardcoded filter: queries that aren't covered by CI?
• Verify snapshot accuracy — DB-dependent snapshots (graphql/test, graphql/server-test) were restored from git and manually edited (filter: → where:). CI is passing, but review the snapshot diffs to ensure no unintended schema changes
• Verify no external consumers — Confirm nothing outside the monorepo imports the deleted packages (graphile-tsvector, graphile-bm25, graphile-trgm, graphile-pgvector)
• Run codegen on consuming repos — constructive-hub and any other repos using the SDK need to regenerate types since the GraphQL argument name changed from filter to where

Test Plan

1. ✅ CI is green — 42/42 checks passing (includes all 21 unified search tests + 61 search integration tests + knative-job-service e2e tests)
2. ✅ Local pnpm build completed successfully with no type errors
3. ✅ Search integration tests validate end-to-end behavior (tsvector, trgm, pgvector)
4. ✅ Snapshots regenerated locally for non-DB tests (graphql/query, graphql/codegen)
5. ✅ DB-dependent snapshots restored and updated for where argument
6. ✅ knative-job-service tests now passing (fixed hardcoded filter: queries in send-email-link function)
7. ⏳ Manual testing recommended:
   • Test where: argument in GraphQL queries works correctly
   • Test connectionFilterArgumentName option with custom values
   • Verify existing clients can configure backward compatibility via connectionFilterArgumentName: 'filter'
   • Test constructive-hub PR Res/migrate fix #166 with updated submodule
   • Verify send-email-link function works end-to-end in deployed environments

Notes

• Breaking change (search consolidation): No deprecation period — the 4 individual packages are deleted entirely
• Breaking change (filter→where rename): GraphQL argument renamed from filter to where. Configurable via connectionFilterArgumentName schema option for backward compatibility
• Runtime bug fixed: The send-email-link function had hardcoded GraphQL queries using condition:/filter: arguments that caused HTTP 400 errors. These are now fixed and use where: with proper filter syntax
• Snapshot editing approach: DB-dependent snapshots were restored from the parent commit and manually edited to replace filter: → where: argument references. CI passing validates the edits are correct
• Cumulative diff: This PR builds on feat: add v5-native graphile-connection-filter plugin #797–feat: v5-native filter system — complete rewrite with declarative API, full test coverage, and new plugins #813 (connection filter rewrite, plugin renames, etc.). The diff includes ~50 files changed
• Translation layer removed: Codegen previously translated SDK where → GraphQL filter via argName: 'filter'. Since GraphQL now uses where by default, the translation is removed
• Type names unchanged: Filter type names stay as UserFilter, StringFilter, etc. — only the argument name changed to where
• constructive-hub integration: PR Res/migrate fix #166 updates the submodule and is waiting on CI

---

Devin Session: https://app.devin.ai/sessions/cf88f3fd383b4421a5169ed01612899d
Requested by: @pyramation

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Devin Review found 2 potential issues.

View 5 additional findings in Devin Review.

[devin-ai-integration]

🔴 trgm operator resolve returns null which is passed unchecked to $where.where()

The similarTo and wordSimilarTo operators in graphile-trgm/src/preset.ts:38-41 and graphile-trgm/src/preset.ts:63-66 can return null when the input value is an empty string (e.g., { value: "" }). The TrgmSearchInput.value field is String! (non-null), but an empty string passes GraphQL validation. When resolve returns null, graphile-connection-filter/src/plugins/operatorApply.ts:110 calls $where.where(null) without checking for null, which will pass null to PgCondition.where() — a method that expects a SQL fragment. This can cause a runtime error or produce invalid SQL.

Trace through the code path

1. User sends filter: { name: { similarTo: { value: "" } } }
2. operatorApply.ts:45-89 validates the outer value object (non-null ✓)
3. operatorApply.ts:105 calls resolve(sqlIdentifier, sqlValue, {value: "", threshold: undefined}, ...)
4. preset.ts:40: !value evaluates !"" → true → returns null
5. operatorApply.ts:110: $where.where(null) is called

Suggested change

	const fragment = resolve(sqlIdentifier, sqlValue, value, $where, {
	fieldName: parentFieldName ?? null,
	operatorName: fieldName,
	});
	$where.where(fragment);
	// Generate the WHERE clause fragment and apply it
	const fragment = resolve(sqlIdentifier, sqlValue, value, $where, {
	fieldName: parentFieldName ?? null,
	operatorName: fieldName,
	});
	if (fragment != null) {
	$where.where(fragment);
	}

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 Duplicate connectionFilterOperatorFactories from sub-presets are silently lost when used standalone

Each sub-preset (PgSearchPreset, TrgmSearchPreset, GraphilePostgisPreset) defines its own connectionFilterOperatorFactories array. When these presets are composed via extends, graphile-config replaces arrays (not concatenates). In ConstructivePreset this is handled by explicitly collecting all factories at graphile/graphile-settings/src/presets/constructive-preset.ts:159-163. However, if a user composes the sub-presets directly (e.g., extends: [PgSearchPreset(), TrgmSearchPreset(), GraphilePostgisPreset]), only the last preset's factories survive — the earlier presets' matches and similarTo/wordSimilarTo operators would be silently dropped. The TrgmSearchPreset() preset at graphile/graphile-trgm/src/preset.ts:96-99 and PgSearchPreset() at graphile/graphile-tsvector/src/preset.ts:72-75 each declare their factories independently with no guidance that they'll be overwritten when combined.

---

Was this helpful? React with 👍 or 👎 to provide feedback.