{"id":13683563,"url":"https://github.com/graphile-contrib/postgraphile-plugin-connection-filter","last_synced_at":"2025-05-15T00:14:49.552Z","repository":{"id":25247773,"uuid":"103549685","full_name":"graphile-contrib/postgraphile-plugin-connection-filter","owner":"graphile-contrib","description":"Filtering on PostGraphile connections","archived":false,"fork":false,"pushed_at":"2025-03-25T08:41:57.000Z","size":2529,"stargazers_count":286,"open_issues_count":28,"forks_count":31,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-05-09T08:18:54.215Z","etag":null,"topics":["filter","graphile","graphile-build","plugin","postgraphile","postgraphql"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/graphile-contrib.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-09-14T15:29:36.000Z","updated_at":"2025-02-24T12:55:54.000Z","dependencies_parsed_at":"2024-01-14T15:26:17.723Z","dependency_job_id":"2981410d-2d86-4c9e-9103-48184b8f03fa","html_url":"https://github.com/graphile-contrib/postgraphile-plugin-connection-filter","commit_stats":{"total_commits":365,"total_committers":12,"mean_commits":"30.416666666666668","dds":0.2684931506849315,"last_synced_commit":"fcd5e920c50604063c5db9bc28c557bd69bcfdcc"},"previous_names":[],"tags_count":73,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile-contrib%2Fpostgraphile-plugin-connection-filter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile-contrib%2Fpostgraphile-plugin-connection-filter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile-contrib%2Fpostgraphile-plugin-connection-filter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphile-contrib%2Fpostgraphile-plugin-connection-filter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphile-contrib","download_url":"https://codeload.github.com/graphile-contrib/postgraphile-plugin-connection-filter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254249205,"owners_count":22039029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filter","graphile","graphile-build","plugin","postgraphile","postgraphql"],"created_at":"2024-08-02T13:02:15.588Z","updated_at":"2025-05-15T00:14:44.540Z","avatar_url":"https://github.com/graphile-contrib.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"[![Package on npm](https://img.shields.io/npm/v/postgraphile-plugin-connection-filter.svg)](https://www.npmjs.com/package/postgraphile-plugin-connection-filter)\n\n# postgraphile-plugin-connection-filter\n\nAdds a powerful suite of filtering capabilities to a PostGraphile schema.\n\n\u003e **Warning:** Use of this plugin with the default options may make it **astoundingly trivial** for a malicious actor (or a well-intentioned application that generates complex GraphQL queries) to overwhelm your database with expensive queries. See the [Performance and Security](https://github.com/graphile-contrib/postgraphile-plugin-connection-filter#performance-and-security) section below for details.\n\n## Usage\n\nRequires PostGraphile v4.5.0 or higher.\n\nInstall with:\n\n```\nyarn add postgraphile postgraphile-plugin-connection-filter\n```\n\nCLI usage via `--append-plugins`:\n\n```\npostgraphile --append-plugins postgraphile-plugin-connection-filter -c postgres://localhost/my_db ...\n```\n\nLibrary usage via `appendPlugins`:\n\n```ts\nimport ConnectionFilterPlugin from \"postgraphile-plugin-connection-filter\";\n// or: const ConnectionFilterPlugin = require(\"postgraphile-plugin-connection-filter\");\n\nconst middleware = postgraphile(DATABASE_URL, SCHEMAS, {\n  appendPlugins: [ConnectionFilterPlugin],\n});\n```\n\n## Performance and Security\n\nBy default, this plugin:\n\n- Exposes a large number of filter operators, including some that can perform expensive pattern matching.\n- Allows filtering on [computed columns](https://www.graphile.org/postgraphile/computed-columns/), which can result in expensive operations.\n- Allows filtering on functions that return `setof`, which can result in expensive operations.\n- Allows filtering on List fields (Postgres arrays), which can result in expensive operations.\n\nTo protect your server, you can:\n\n- Use the `connectionFilterAllowedFieldTypes` and `connectionFilterAllowedOperators` options to limit the filterable fields and operators exposed through GraphQL.\n- Set `connectionFilterComputedColumns: false` to prevent filtering on [computed columns](https://www.graphile.org/postgraphile/computed-columns/).\n- Set `connectionFilterSetofFunctions: false` to prevent filtering on functions that return `setof`.\n- Set `connectionFilterArrays: false` to prevent filtering on List fields (Postgres arrays).\n\nAlso see the [Production Considerations](https://www.graphile.org/postgraphile/production) page of the official PostGraphile docs, which discusses query whitelisting.\n\n## Features\n\nThis plugin supports filtering on almost all PostgreSQL types, including complex types such as domains, ranges, arrays, and composite types. For details on the specific operators supported for each type, see [docs/operators.md](https://github.com/graphile-contrib/postgraphile-plugin-connection-filter/blob/master/docs/operators.md).\n\nSee also:\n\n- [@graphile/pg-aggregates](https://github.com/graphile/pg-aggregates) - integrates with this plugin to enable powerful aggregate filtering\n- [postgraphile-plugin-connection-filter-postgis](https://github.com/graphile-contrib/postgraphile-plugin-connection-filter-postgis) - adds PostGIS functions and operators for filtering on `geography`/`geometry` columns\n- [postgraphile-plugin-fulltext-filter](https://github.com/mlipscombe/postgraphile-plugin-fulltext-filter) - adds a full text search operator for filtering on `tsvector` columns\n- [postgraphile-plugin-unaccented-text-search-filter](https://github.com/spacefill/postgraphile-plugin-unaccented-text-search-filter) - adds unaccent text search operators\n\n## Handling `null` and empty objects\n\nBy default, this plugin will throw an error when `null` literals or empty objects (`{}`) are included in `filter` input objects. This prevents queries with ambiguous semantics such as `filter: { field: null }` and `filter: { field: { equalTo: null } }` from returning unexpected results. For background on this decision, see https://github.com/graphile-contrib/postgraphile-plugin-connection-filter/issues/58.\n\nTo allow `null` and `{}` in inputs, use the `connectionFilterAllowNullInput` and `connectionFilterAllowEmptyObjectInput` options documented under [Plugin Options](https://github.com/graphile-contrib/postgraphile-plugin-connection-filter#plugin-options). Please note that even with `connectionFilterAllowNullInput` enabled, `null` is never interpreted as a SQL `NULL`; fields with `null` values are simply ignored when resolving the query.\n\n## Plugin Options\n\nWhen using PostGraphile as a library, the following plugin options can be passed via `graphileBuildOptions`:\n\n#### connectionFilterAllowedOperators\n\nRestrict filtering to specific operators:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterAllowedOperators: [\n      \"isNull\",\n      \"equalTo\",\n      \"notEqualTo\",\n      \"distinctFrom\",\n      \"notDistinctFrom\",\n      \"lessThan\",\n      \"lessThanOrEqualTo\",\n      \"greaterThan\",\n      \"greaterThanOrEqualTo\",\n      \"in\",\n      \"notIn\",\n    ],\n  },\n});\n```\n\n#### connectionFilterAllowedFieldTypes\n\nRestrict filtering to specific field types:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterAllowedFieldTypes: [\"String\", \"Int\"],\n  },\n});\n```\n\nThe available field types will depend on your database schema.\n\n#### connectionFilterArrays\n\nEnable/disable filtering on PostgreSQL arrays:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterArrays: false, // default: true\n  },\n});\n```\n\n#### connectionFilterComputedColumns\n\nEnable/disable filtering by computed columns:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterComputedColumns: false, // default: true\n  },\n});\n```\n\nConsider setting this to `false` and using `@filterable` [smart comments](https://www.graphile.org/postgraphile/smart-comments/) to selectively enable filtering:\n\n```sql\ncreate function app_public.foo_computed(foo app_public.foo)\n  returns ... as $$ ... $$ language sql stable;\n\ncomment on function app_public.foo_computed(foo app_public.foo) is E'@filterable';\n```\n\n#### connectionFilterOperatorNames\n\nUse alternative names (e.g. `eq`, `ne`) for operators:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterOperatorNames: {\n      equalTo: \"eq\",\n      notEqualTo: \"ne\",\n    },\n  },\n});\n```\n\n#### connectionFilterRelations\n\nEnable/disable filtering on related fields:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterRelations: true, // default: false\n  },\n});\n```\n\n#### connectionFilterSetofFunctions\n\nEnable/disable filtering on functions that return `setof`:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterSetofFunctions: false, // default: true\n  },\n});\n```\n\nConsider setting this to `false` and using `@filterable` [smart comments](https://www.graphile.org/postgraphile/smart-comments/) to selectively enable filtering:\n\n```sql\ncreate function app_public.some_foos()\n  returns setof ... as $$ ... $$ language sql stable;\n\ncomment on function app_public.some_foos() is E'@filterable';\n```\n\n#### connectionFilterLogicalOperators\n\nEnable/disable filtering with logical operators (`and`/`or`/`not`):\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterLogicalOperators: false, // default: true\n  },\n});\n```\n\n#### connectionFilterAllowNullInput\n\nAllow/forbid `null` literals in input:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterAllowNullInput: true, // default: false\n  },\n});\n```\n\nWhen `false`, passing `null` as a field value will throw an error.\nWhen `true`, passing `null` as a field value is equivalent to omitting the field.\n\n#### connectionFilterAllowEmptyObjectInput\n\nAllow/forbid empty objects (`{}`) in input:\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterAllowEmptyObjectInput: true, // default: false\n  },\n});\n```\n\nWhen `false`, passing `{}` as a field value will throw an error.\nWhen `true`, passing `{}` as a field value is equivalent to omitting the field.\n\n#### connectionFilterUseListInflectors\n\nWhen building the \"many\" relationship filters, if this option is set `true`\nthen we will use the \"list\" field names rather than the \"connection\" field\nnames when naming the fields in the filter input. This would be desired if you\nhave `simpleCollection` set to `\"only\"` or `\"both\"` and you've simplified your\ninflection to omit the `-list` suffix, e.g. using\n`@graphile-contrib/pg-simplify-inflector`'s `pgOmitListSuffix` option. Use this\nif you see `Connection` added to your filter field names.\n\n```js\npostgraphile(pgConfig, schema, {\n  graphileBuildOptions: {\n    connectionFilterUseListInflectors: true, // default: false\n  },\n});\n```\n\n## Examples\n\n```graphql\nquery {\n  allPosts(filter: {\n    createdAt: { greaterThan: \"2021-01-01\" }\n  }) {\n    ...\n  }\n}\n```\n\nFor an extensive set of examples, see [docs/examples.md](https://github.com/graphile-contrib/postgraphile-plugin-connection-filter/blob/master/docs/examples.md).\n\n## Development\n\nTo establish a test environment, create an empty PostgreSQL database with C collation (required for consistent ordering of strings) and set a `TEST_DATABASE_URL` environment variable with your database connection string.\n\n```bash\ncreatedb graphile_test_c --template template0 --lc-collate C\nexport TEST_DATABASE_URL=postgres://localhost:5432/graphile_test_c\nyarn\nyarn test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphile-contrib%2Fpostgraphile-plugin-connection-filter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphile-contrib%2Fpostgraphile-plugin-connection-filter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphile-contrib%2Fpostgraphile-plugin-connection-filter/lists"}