Skip to content

feat(pgvector): move vector search from condition to filter argument#796

Merged
pyramation merged 2 commits intomainfrom
devin/1773291168-vector-filter-migration
Mar 12, 2026
Merged

feat(pgvector): move vector search from condition to filter argument#796
pyramation merged 2 commits intomainfrom
devin/1773291168-vector-filter-migration

Conversation

@pyramation
Copy link
Contributor

feat(pgvector): move vector search from condition to filter argument

Summary

Migrates vector embedding search fields from PostGraphile's built-in condition argument to the connection filter plugin's filter argument for unified filtering DX. All vector search inputs now live alongside PostGIS and column filters under filter:.

Before:

allDocuments(condition: { vectorEmbedding: { vector: [...], metric: COSINE, distance: 0.5 } })

After:

allDocuments(filter: { vectorEmbedding: { vector: [...], metric: COSINE, distance: 0.5 } })

Key changes in graphile-pgvector-plugin:

  • vector-search.ts: Scope check changed from isPgConditionisPgConnectionFilter. Plugin ordering updated to load after PgConnectionArgFilterPlugin. The core apply function logic is unchanged — the v5 connection filter plugin creates PgCondition wrapping PgSelectStep in its apply chain, so getQueryBuilder() traversal, selectAndReturnIndex, setMeta, and orderBy should all work identically.
  • types.ts: conditionPrefix option renamed to filterPrefix (old name kept as @deprecated alias).
  • package.json: postgraphile-plugin-connection-filter promoted from optional to required peer dependency.
  • Tests: All queries updated from condition: to filter:, PostGraphileConnectionFilterPreset added to test preset.

Review & Testing Checklist for Human

  • Verify getQueryBuilder() parent traversal works under the filter's PgCondition chain. This is the highest risk item. The approach assumes the connection filter plugin's v5 applyPlan creates a PgCondition(pgSelectStep) with the same parent structure as the native condition system. If the parent chain differs, selectAndReturnIndex/setMeta/orderBy will silently fail (distance field returns null, ordering doesn't apply). Run the vector-search tests (cd graphile/graphile-pgvector-plugin && pnpm test) against a real Postgres instance with pgvector to confirm.
  • Verify apply function is invoked by the connection filter system. The field is registered with an apply: property, but the connection filter plugin's v5 adaptation may use a different invocation pattern than native condition fields. Confirm filter queries actually trigger the apply function and produce correct SQL.
  • Breaking GraphQL API change: All consumers using condition: { vectorEmbedding: ... } must update to filter: { vectorEmbedding: ... }. Check for any other packages in the monorepo (codegen, server-test, etc.) that may reference the old query shape.
  • Confirm embeddingDistance output field and EMBEDDING_DISTANCE_ASC/DESC orderBy still work. These hooks are unchanged but rely on the meta system being populated by the filter's apply function. Test with filter: { vectorEmbedding: {...} } + orderBy: EMBEDDING_DISTANCE_ASC to verify end-to-end.

Notes

  • TypeScript escapes: scope: { isPgConnectionFilter, pgCodec } = {} as any and isPgConnectionFilterField: true as any are type escape hatches. The connection filter plugin is a v4 plugin adapted for v5, so its scope properties aren't in PostGraphile's v5 type declarations. These casts are necessary but mean wrong scope property names would silently fail instead of producing type errors.
  • No local testing performed: Tests were updated but not executed. Build passes (TypeScript compiles) but runtime behavior is unverified.
  • Preset ordering: ConstructivePreset already loads PostGraphileConnectionFilterPreset before VectorSearchPlugin in its extends array, which should satisfy the new dependency, but this wasn't verified.

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

Migrates vector embedding search fields from PostGraphile's built-in
`condition` argument to the connection filter plugin's `filter` argument.

Changes:
- Scope check: isPgCondition -> isPgConnectionFilter
- Field scope: isPgConnectionConditionInputField -> isPgConnectionFilterField
- Plugin ordering: add PgConnectionArgFilterPlugin to after[] deps
- Rename conditionPrefix option to filterPrefix (backwards compat kept)
- Make postgraphile-plugin-connection-filter a required peer dependency
- Update all tests to use filter: instead of condition:
- Add PostGraphileConnectionFilterPreset to test preset

The core apply function logic is unchanged since the v5 connection
filter plugin uses PgCondition wrapping PgSelectStep — identical to
the condition approach. getQueryBuilder() traversal, selectAndReturnIndex,
setMeta, and orderBy all work the same way.
@devin-ai-integration
Copy link
Contributor

🤖 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

@pyramation pyramation merged commit f52b5d3 into main Mar 12, 2026
42 checks passed
@pyramation pyramation deleted the devin/1773291168-vector-filter-migration branch March 12, 2026 06:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant