diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterArgPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterArgPlugin.ts index 2296ae74c..edd0479e1 100644 --- a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterArgPlugin.ts +++ b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterArgPlugin.ts @@ -7,9 +7,10 @@ const version = '1.0.0'; /** * ConnectionFilterArgPlugin * - * Adds the filter argument (configurable name, default 'where') to connection - * and simple collection fields. Uses `applyPlan` to create a PgCondition that - * child filter fields can add WHERE clauses to. + * Adds the `where` argument (name configurable via + * `connectionFilterArgumentName`, default `'where'`) to connection and + * simple collection fields. Uses `applyPlan` to create a PgCondition + * that child filter fields can add WHERE clauses to. * * This runs before PgConnectionArgOrderByPlugin so that filters are applied * before ordering (important for e.g. full-text search rank ordering). @@ -17,7 +18,7 @@ const version = '1.0.0'; export const ConnectionFilterArgPlugin: GraphileConfig.Plugin = { name: 'ConnectionFilterArgPlugin', version, - description: 'Adds the filter argument to connection and list fields', + description: 'Adds the `where` argument to connection and list fields', before: ['PgConnectionArgOrderByPlugin'], schema: { @@ -100,7 +101,7 @@ export const ConnectionFilterArgPlugin: GraphileConfig.Plugin = { fieldArg.apply( $pgSelect, (queryBuilder: any, value: any) => { - // If filter is null/undefined or empty {}, treat as "no filter" — skip + // If where is null/undefined or empty {}, treat as "no filter" — skip if (value == null || isEmpty(value)) return; const condition = new PgCondition(queryBuilder); if (attributeCodec) { @@ -126,7 +127,7 @@ export const ConnectionFilterArgPlugin: GraphileConfig.Plugin = { fieldArg.apply( $pgSelect, (queryBuilder: any, value: any) => { - // If filter is null/undefined or empty {}, treat as "no filter" — skip + // If where is null/undefined or empty {}, treat as "no filter" — skip if (value == null || isEmpty(value)) return; const condition = new PgCondition(queryBuilder); if (attributeCodec) { @@ -143,7 +144,7 @@ export const ConnectionFilterArgPlugin: GraphileConfig.Plugin = { }), }, }, - `Adding connection filter '${argName}' arg to field '${fieldName}' of '${Self.name}'` + `Adding connection where arg '${argName}' to field '${fieldName}' of '${Self.name}'` ); }, }, diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterAttributesPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterAttributesPlugin.ts index 806c0e3ac..f01c32ce1 100644 --- a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterAttributesPlugin.ts +++ b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterAttributesPlugin.ts @@ -96,7 +96,7 @@ export const ConnectionFilterAttributesPlugin: GraphileConfig.Plugin = { if (isEmpty(value)) { throw Object.assign( new Error( - 'Empty objects are forbidden in filter argument input.' + 'Empty objects are forbidden in where argument input.' ), {} ); @@ -107,7 +107,7 @@ export const ConnectionFilterAttributesPlugin: GraphileConfig.Plugin = { ) { throw Object.assign( new Error( - 'Null literals are forbidden in filter argument input.' + 'Null literals are forbidden in where argument input.' ), {} ); diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterBackwardRelationsPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterBackwardRelationsPlugin.ts index 8e7a41c11..6b9d6084c 100644 --- a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterBackwardRelationsPlugin.ts +++ b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterBackwardRelationsPlugin.ts @@ -15,7 +15,7 @@ const version = '1.0.0'; * * For unique backward relations (one-to-one), a single filter field is added: * ```graphql - * allClients(filter: { + * allClients(where: { * profileByClientId: { bio: { includes: "engineer" } } * }) { ... } * ``` @@ -23,7 +23,7 @@ const version = '1.0.0'; * For non-unique backward relations (one-to-many), a "many" filter type is added * with `some`, `every`, and `none` sub-fields: * ```graphql - * allClients(filter: { + * allClients(where: { * ordersByClientId: { some: { total: { greaterThan: 1000 } } } * }) { ... } * ``` diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterComputedAttributesPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterComputedAttributesPlugin.ts index ce0c6c7b5..776728895 100644 --- a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterComputedAttributesPlugin.ts +++ b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterComputedAttributesPlugin.ts @@ -18,7 +18,7 @@ const version = '1.0.0'; * * This plugin adds a `fullName` filter field to `PersonFilter`, typed as `StringFilter`, * allowing queries like: - * { people(filter: { fullName: { startsWith: "John" } }) { ... } } + * { people(where: { fullName: { startsWith: "John" } }) { ... } } * * Controlled by the `connectionFilterComputedColumns` schema option (default: true). * Requires the `filterBy` behavior on the pgResource to be enabled. diff --git a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterForwardRelationsPlugin.ts b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterForwardRelationsPlugin.ts index 1445d7a7e..34f711bfb 100644 --- a/graphile/graphile-connection-filter/src/plugins/ConnectionFilterForwardRelationsPlugin.ts +++ b/graphile/graphile-connection-filter/src/plugins/ConnectionFilterForwardRelationsPlugin.ts @@ -18,7 +18,7 @@ const version = '1.0.0'; * allowing queries like: * * ```graphql - * allOrders(filter: { + * allOrders(where: { * clientByClientId: { name: { startsWith: "Acme" } } * }) { ... } * ``` diff --git a/graphile/graphile-connection-filter/src/plugins/operatorApply.ts b/graphile/graphile-connection-filter/src/plugins/operatorApply.ts index cf8d02b83..042e7599d 100644 --- a/graphile/graphile-connection-filter/src/plugins/operatorApply.ts +++ b/graphile/graphile-connection-filter/src/plugins/operatorApply.ts @@ -83,7 +83,7 @@ export function makeApplyFromOperatorSpec( } if (!connectionFilterAllowNullInput && value === null) { throw Object.assign( - new Error('Null literals are forbidden in filter argument input.'), + new Error('Null literals are forbidden in where argument input.'), {} ); } diff --git a/graphile/graphile-connection-filter/src/utils.ts b/graphile/graphile-connection-filter/src/utils.ts index 411798206..0222d3ec3 100644 --- a/graphile/graphile-connection-filter/src/utils.ts +++ b/graphile/graphile-connection-filter/src/utils.ts @@ -116,11 +116,11 @@ export function makeAssertAllowed(build: any): (value: unknown, mode: 'object' | isEmpty: (o: unknown) => boolean ) => function (value: unknown, mode: 'object' | 'list') { - // Reject empty objects in nested filter contexts (and/or/not, relation filters) + // Reject empty objects in nested where contexts (and/or/not, relation filters) if (mode === 'object' && isEmpty(value)) { throw Object.assign( new Error( - 'Empty objects are forbidden in filter argument input.' + 'Empty objects are forbidden in where argument input.' ), {} ); @@ -134,7 +134,7 @@ export function makeAssertAllowed(build: any): (value: unknown, mode: 'object' | if (isEmpty(arr[i])) { throw Object.assign( new Error( - 'Empty objects are forbidden in filter argument input.' + 'Empty objects are forbidden in where argument input.' ), {} ); @@ -147,7 +147,7 @@ export function makeAssertAllowed(build: any): (value: unknown, mode: 'object' | if (!connectionFilterAllowNullInput && value === null) { throw Object.assign( new Error( - 'Null literals are forbidden in filter argument input.' + 'Null literals are forbidden in where argument input.' ), {} ); diff --git a/graphile/graphile-postgis/src/plugins/spatial-relations.ts b/graphile/graphile-postgis/src/plugins/spatial-relations.ts index 2650345e5..daf4984ea 100644 --- a/graphile/graphile-postgis/src/plugins/spatial-relations.ts +++ b/graphile/graphile-postgis/src/plugins/spatial-relations.ts @@ -46,7 +46,7 @@ import type { PostgisExtensionInfo } from './detect-extension'; * Generated GraphQL (for the `st_dwithin` case): * * ```graphql - * telemedicineClinics(filter: { + * telemedicineClinics(where: { * nearbyClinic: { * distance: 5000, * some: { specialty: { eq: "pediatrics" } } diff --git a/graphile/graphile-settings/__tests__/preset-integration.test.ts b/graphile/graphile-settings/__tests__/preset-integration.test.ts index 39a8d3fb6..db4f0c533 100644 --- a/graphile/graphile-settings/__tests__/preset-integration.test.ts +++ b/graphile/graphile-settings/__tests__/preset-integration.test.ts @@ -131,7 +131,7 @@ describe('Schema introspection', () => { expect(fieldNames).toContain('embedding'); }); - it('locations connection exists and has filter argument but no condition', async () => { + it('locations connection exists and has where argument but no condition', async () => { const result = await query<{ __type: { fields: { name: string; args: { name: string }[] }[] } | null }>({ query: ` query { diff --git a/graphile/graphile-settings/src/plugins/enable-all-filter-columns.ts b/graphile/graphile-settings/src/plugins/enable-all-filter-columns.ts index 331fde05b..6dd935aca 100644 --- a/graphile/graphile-settings/src/plugins/enable-all-filter-columns.ts +++ b/graphile/graphile-settings/src/plugins/enable-all-filter-columns.ts @@ -39,7 +39,7 @@ import type { GraphileConfig } from 'graphile-config'; * and adds `+attribute:filterBy` and `+attribute:orderBy` back to ALL columns, regardless of index status. * * This means: - * - All columns will appear in the connection filter's filter argument + * - All columns will appear in the connection filter's `where` argument * - All columns will appear in the connection's orderBy enum * - Developers can filter and sort by any column * - It's the developer's/DBA's responsibility to add indexes for frequently filtered/sorted columns diff --git a/graphile/graphile-settings/src/presets/constructive-preset.ts b/graphile/graphile-settings/src/presets/constructive-preset.ts index 96db1d204..d8024bcda 100644 --- a/graphile/graphile-settings/src/presets/constructive-preset.ts +++ b/graphile/graphile-settings/src/presets/constructive-preset.ts @@ -54,8 +54,8 @@ import { getBucketProvisionerConnection } from '../bucket-provisioner-resolver'; * * RELATION FILTERS: * - Enabled via connectionFilterRelations: true - * - Forward: filter child by parent (e.g. allOrders(filter: { clientByClientId: { name: { startsWith: "Acme" } } })) - * - Backward: filter parent by children (e.g. allClients(filter: { ordersByClientId: { some: { total: { greaterThan: 1000 } } } })) + * - Forward: filter child by parent (e.g. allOrders(where: { clientByClientId: { name: { startsWith: "Acme" } } })) + * - Backward: filter parent by children (e.g. allClients(where: { ordersByClientId: { some: { total: { greaterThan: 1000 } } } })) * * USAGE: * ```typescript @@ -105,9 +105,11 @@ export const ConstructivePreset: GraphileConfig.Preset = { ], /** * Disable PostGraphile core's condition argument entirely. - * All filtering now lives under the `filter` argument via our v5-native - * graphile-connection-filter plugin. Search, BM25, pgvector, and PostGIS - * filter fields all hook into `isPgConnectionFilter` instead of `isPgCondition`. + * All filtering now lives under the `where` argument via our v5-native + * graphile-connection-filter plugin (which renames the default `filter` + * argument to `where` via `connectionFilterArgumentName: 'where'`). + * Search, BM25, pgvector, and PostGIS filter fields all hook into + * `isPgConnectionFilter` instead of `isPgCondition`. */ disablePlugins: [ 'PgConditionArgumentPlugin', @@ -116,7 +118,7 @@ export const ConstructivePreset: GraphileConfig.Preset = { /** * Connection Filter Plugin Configuration * - * These options control what fields appear in the `filter` argument on connections. + * These options control what fields appear in the `where` argument on connections. * Our v5-native graphile-connection-filter plugin controls relation filters via the * `connectionFilterRelations` option passed to ConnectionFilterPreset(). * @@ -144,14 +146,14 @@ export const ConstructivePreset: GraphileConfig.Preset = { /** * connectionFilterLogicalOperators: true (default) * Keeps `and`, `or`, `not` operators for combining filter conditions. - * Example: filter: { or: [{ name: { eq: "foo" } }, { name: { eq: "bar" } }] } + * Example: where: { or: [{ name: { eq: "foo" } }, { name: { eq: "bar" } }] } */ connectionFilterLogicalOperators: true, /** * connectionFilterArrays: true (default) * Allows filtering on PostgreSQL array columns. - * Example: filter: { tags: { contains: ["important"] } } + * Example: where: { tags: { contains: ["important"] } } */ connectionFilterArrays: true,