|
| 1 | +--- |
| 2 | +title: Input Based Breaking Change Detection |
| 3 | +description: |
| 4 | + Improvements to Hive's breaking change detection to make it easier and safer to migrate schemas. |
| 5 | +date: 2025-05-20 |
| 6 | +authors: [jdolle] |
| 7 | +--- |
| 8 | + |
| 9 | +## What’s New? |
| 10 | + |
| 11 | +- **Hive accounts for argument, input field, and variable values when checking for breaking |
| 12 | + changes** – This improvement is fully backwards compatible and will automatically take effect when |
| 13 | + upgrading your hive client package(s). |
| 14 | + |
| 15 | +Compatible client versions include versions greater than or equal to: |
| 16 | + |
| 17 | +- @graphql-hive/apollo@0.39.1 |
| 18 | +- @graphql-hive/envelop@0.36.1 |
| 19 | +- @graphql-hive/yoga@0.42.1 |
| 20 | + |
| 21 | +## Feature Details |
| 22 | + |
| 23 | +Breaking change detection is complicated. It starts in the |
| 24 | +[graphql-hive client packages](https://the-guild.dev/graphql/hive/docs/api-reference/client), where |
| 25 | +operations are processed into a list of requested fields and types. |
| 26 | + |
| 27 | +For example, an operation `{ user(id: "1234") { id } }` will produce this list of coordinates: |
| 28 | + |
| 29 | +- Query |
| 30 | +- Query.user |
| 31 | +- Query.user.id |
| 32 | +- User |
| 33 | +- User.id |
| 34 | +- ID |
| 35 | + |
| 36 | +These coordinates, along with other useful metrics like latency and error status, are sent to Hive's |
| 37 | +servers in batches from the client(s). Hive processes and stores this usage data by timestamp and |
| 38 | +coordinate. These are then aggregated over time to produce what's seen on Hive's explorer and |
| 39 | +insights pages, as well as to detect whether not a specific change to the schema will break clients. |
| 40 | + |
| 41 | +This approach works well, but previously, it only collected from the type definitions used by the |
| 42 | +operation. But this release adds an additional coordinate for inputs with an indicator if the data |
| 43 | +is provided by clients, either as a value or variable. |
| 44 | + |
| 45 | +For the above example, an additional coordinate is generated: |
| 46 | + |
| 47 | +- Query.user.id! |
| 48 | + |
| 49 | +The exclamation (!) indicates that this argument was passed a value. This helps distinguish whether |
| 50 | +or not an input field or argument can be converted from nullable to non-nullable safely. |
| 51 | + |
| 52 | +We are excited about this feature because it provides greater accuracy and convenience for our |
| 53 | +users, while keeping their schemas safe. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +[For more information about conditional breaking changes, see the Target Management docs](/docs/management/targets#conditional-breaking-changes). |
0 commit comments