从 API 版本 2026-10 开始，GraphQL Admin API 会在查询按未配置为可过滤的元字段进行过滤时返回错误，而不是静默返回不正确的结果。这是一个破坏性更改。它影响在版本 2026-10 或更高版本上按元字段过滤资源的應用程序，您需要在升级之前更新受影响的查询。
变更内容
在 API 版本 2026-10 及更高版本中，GraphQL Admin API 会在执行查询之前检查元字段过滤器。如果查询按不能用于过滤的元字段进行过滤，则查询将返回解释问题的错误，而不是忽略无效谓词并返回不正确的结果。
元字段过滤器通常在以下情况下失败：
- 元字段没有定义。
- 元字段的定义未配置为允许过滤。
- 元字段的类型不支持您使用的过滤器或比较操作。
以前，元字段过滤器中的无效谓词会被静默忽略，因此带有无效过滤器的查询可能会返回误导性结果。现在，响应会告知您过滤器是问题所在，以便您可以对其进行修正。
受影响对象
此更改会影响在 API 版本 2026-10 或更高版本上使用 GraphQL Admin API 按元字段进行过滤的应用程序和集成（例如，按元字段过滤产品、订单或客户）。在版本 2026-07 及更早版本上的查询保持以前的行为，在您升级之前不受影响。
仅当查询按不适合过滤的元字段进行过滤时，您才会受到影响。使用支持的比较操作并按已配置为可过滤的元字段进行过滤的查询行为与以前完全相同，并返回相同的结果。
为何重要
静默返回不正确的结果使得难以发现无效的元字段过滤器：拼写错误或不受支持的过滤器看起来与仅仅匹配项不同的查询完全相同。改为返回错误可以让您在开发阶段发现和修复这些问题，而不是在生产环境中部署一个 quietly 返回空结果的过滤器。
破坏性更改和迁移
API 版本 2026-10 计划于 2026 年 10 月 1 日发布。一旦您在 2026-10 或更高版本上发出请求，按未配置为可过滤的元字段进行过滤的查询将返回错误，而不是空结果。
迁移步骤：
- 在您的应用中，查找通过 GraphQL Admin API 按 metafield 进行过滤的查询。
- 对于每一个，请确认该元字段具有定义、该定义允许过滤，并且您使用的比较方式适用于该元字段的类型。
- 更新任何引用未配置为可过滤的 metafield 的过滤器。
- 使用版本 2026-10 测试您的查询，并确认它们能无错误地返回结果。
如果您依赖的 metafield 尚不支持过滤，请在应用更新完成前，将这些查询保留在版本 2026-07 或更早版本中，并在升级之前先为该 metafield 定义设置过滤功能。