Filtering
Out of the box, PostGraphile supports rudimentary filtering on
connections using a condition argument. This allows you to
filter using equality with specific values (e.g. username: "Alice" or
category: ARTICLE).
PostGraphile 开箱即支持通过 condition 参数对 Connection 进行基础过滤,可用于按特定值做等值匹配(例如 username: "Alice" 或 category: ARTICLE)。
TODO: See an example using the connection argument.
TODO:查看使用 connection 参数的示例。
It’s important when implementing filters to keep performance in mind. By
default (unless you’re using the V4 preset), PostGraphile will not allow you to
filter by a column that isn’t indexed. To force a column to appear in the
filtering options you can applying the @behavior filterBy smart
tag to the relevant column, or you can use @behavior -filterBy
to force it remove it.
实现过滤功能时,务必重视性能问题。默认情况下(除非使用了 V4 preset),PostGraphile 不允许按未建索引的列进行过滤。如果希望强制将某个列加入过滤选项,可以为该列添加 @behavior filterBy smart tag;反之,也可以使用 @behavior -filterBy 将其强制移除。
Advanced filtering高级过滤
You can extend PostGraphile’s schema with more advance filtering capabilities by adding fields using custom queries, computed columns or by using extendSchema.
你可以通过自定义 Query、计算列或 extendSchema 添加字段,为 PostGraphile 的 schema 扩展更高级的过滤能力。
To add a condition to an existing condition another option is the
addPgTableCondition. You
can also augment PostGraphile’s existing connections using custom Graphile
Engine plugins, such as the following:
如果想在现有的 condition 中添加新条件,另一个选择是使用 addPgTableCondition。此外,你也可以编写自定义 Graphile Engine 插件来增强 PostGraphile 现有的 Connection,例如:
Filter Plugin过滤插件
Adding powerful generic filtering capabilities to your GraphQL API is strongly discouraged, not just by Benjie (the maintainer of PostGraphile) but also by Lee Byron (one of the inventors of GraphQL) and various other experts in the GraphQL ecosystem. It is strongly advised that you add only very specific filters using one of the techniques above (and that you make their inputs as simple as possible) rather than using a generic filtering plugin like this. Not heeding this advice may lead to very significant performance issues down the line that are very hard for you to dig your way out of.
在 GraphQL API 中开放强大的通用过滤能力,不仅受到 PostGraphile 维护者 Benjie 的强烈反对,Lee Byron(GraphQL 创造者之一)及 GraphQL 生态中的诸多专家也同样不推荐这种做法。强烈建议你采用上文介绍的方式,只添加高度具体的过滤条件(并尽可能保持其输入简单),而不要使用这类通用过滤插件。若忽视此建议,日后很可能会陷入难以摆脱的严重性能困境。
That said, it's your schema and you know its audience and how it's going to be used better than this documentation does. There are definitely valid use cases for using generic filtering. Make sure you think about it carefully and don't just enable it on a whim.
话虽如此,毕竟这是你的 schema,你比这份文档更了解它的受众和实际使用方式。通用过滤确实存在不少合理的应用场景——只要深思熟虑后再做决定,别一时兴起就随手启用即可。
A very popular plugin is Matt Bretl’s connection-filter plugin, located at
https://github.com/graphile-contrib/postgraphile-plugin-connection-filter.
This adds a filter argument to connections that enables you to use advanced
filters, including filtering on related records from other tables, using greater
than, less than and ranges for filtering, and even filtering against the output
of functions. If you need advanced filtering in your GraphQL API (and you can
use something like
persisted queries to
prevent malicious parties issuing complex requests) then I recommend you check
it out! (But do keep the caveats above in mind.)
Matt Bretl 开发的 connection-filter 插件非常受欢迎,仓库地址为 https://github.com/graphile-contrib/postgraphile-plugin-connection-filter。该插件会为 Connection 添加一个 filter 参数,支持各种高级过滤操作,包括按其他表的关联记录过滤、使用大于/小于及范围条件过滤,甚至可以根据函数的输出值进行过滤。如果你的 GraphQL API 确实需要高级过滤(同时可以通过持久化查询等机制来防止恶意用户构造复杂请求),非常建议你试用一下!(但请务必牢记上文提到的注意事项。)
Other plugins其他插件
Some more of the community plugins relate to filtering, you can read more about them on the community plugins page
社区中还有其他与过滤相关的插件,你可以在社区插件页面了解更多。