Overview

We've introduced schema checks and discussed the important role they play in the management of your graph. In addition to composition checks (which ensure that changes to a subgraph can be successfully composed with other subgraphs), we have another tool to add to our toolbelt: operation checks.

Operation checks compare schema changes against client operations made in the past, to ensure that we're not introducing any breaking changes for clients consuming data from our graph.

In this lesson, we will:

• Learn how to navigate operation checks in Studio
• Learn how to override flagged changes in Studio
• Learn how to re-run checks in Studio

Updating the subgraph

Not only has the Airlock team been working on new features, they've also been keeping an eye on the health of their graph and how clients have been using it. They recently discovered that both the mobile and web clients have been using the schema's featuredListings field and implementing additional logic using the results they receive.

The featuredListings field returns a list of Listing objects. More specifically, it returns exactly eight packages. However, the web client's layout works best when only displaying six of these packages. Meanwhile, the mobile client finds that displaying only three works best for their audience. So currently, both clients are fetching more packages than they need.

We don't want the clients to implement that extra logic by themselves, so let's help them fix that. Let's start back at the beginning of our CI/CD workflow.

👩🏽‍🏫 Lisa from the Listings team has made the listings subgraph schema much more flexible for client queries by adding a new argument to the featuredListings field.

Adding a new argument

Let's look at the listings subgraph. To customize the number of featured listings that can be displayed in the UI, Lisa has added a new non-nullable argument, limit, to include to the featuredListings field.

They also updated the resolvers and data sources accordingly to implement this new schema change.

With the code changes ready to go, let's execute the next step in our workflow: running a schema check locally.

Running the rover subgraph check command results in no composition errors, but now operation checks have failed for some of the changes! Let's dig into the error:

Historically, clients have queried the featuredListings field without the limit argument. If the Listings team pushes this update to the subgraph without giving downstream clients a chance to update their queries, they could be introducing a breaking change.

Operation checks assess whether the proposed changes to the subgraph will affect any GraphQL operations that have been executed against the schema within a certain timeframe. In our team's case, the query for featuredListings runs many times per day, whenever Airlock receives more visitors interested in booking a trip.

Because Airlock is configured to use managed federation, this analytics data about operation usage is automatically collected and stored for our teams to review in Studio. Information about how many times an operation is called by clients provides useful insight into when parts of the schema can be safely changed or even removed.

We can see the data for the GetFeaturedListings operation below:

To fix the error introduced by adding the new limit argument, Lisa from the Listings team modifies the argument to be nullable, and sets 8 as the default value.

By setting the argument as nullable, no breaking changes are introduced and existing client queries work as usual, retrieving eight listings to display as the default.

After running another local schema check, we see the results below:

All good to go! Lisa can run through the whole CI/CD process again to get the change live in production. When this change is live, clients can then work to modify their queries to include the new limit argument. The web client can set it to 6 and the mobile client can set it to 3. No more extra logic needed on the client-side!

We're not done with Airlock graph maintenance yet! Lisa has discovered another field in the listings subgraph that needs updating. In this case, the field should be removed, because no one seems to be using it.

Removing a field

An old field from an abandoned project to re-invent the homepage is still present in the schema: the Listing.photoInHexagonShape field.

An old homepage mock-up shows how this field was intended to be used.

To keep their schema lean and maintainable, Lisa has opted to remove the Listing.photoInHexagonShape field entirely.

When we run schema checks locally, the changes result in an operation error. We can see it in the terminal:

We can also check these results in Studio under the Checks page, or by following the link provided in the terminal output. Based on historical operations executed against our graph, we see the warning that removing this field might cause a breaking change for downstream clients.

To address this operation check error, Lisa first needs to make sure that no one is relying on this field before they remove it. To do so, they'll first mark the field in the schema file with the @deprecated directive and provide a reason (which any downstream clients consuming the field can see). By communicating this deprecated status to clients prior to removing the field, it gives everyone a chance to update their queries and avoid breaking changes.

After running a local schema check, we'll see no errors in the terminal:

We can see that the field has been deprecated in Studio:

After some time has passed, we'll have confidence that any downstream clients that historically queried for the Listing.photoInHexagonShape field have since removed it from their queries.

Lisa can now completely remove the Listing.photoInHexagonShape field, along with its @deprecated directive. We'll go through the CI/CD process again, running a local schema check and investigating the operation check errors on Studio. Knowing that this change is safe, we can override the resulting operation error.

Marking changes as safe

Within the error view in Studio, we can select the Override dropdown and click Mark changes as safe.

This tells the schema checks process that this exact change can be safely ignored in future operation checks, but it does not give the operation itself the green light for any changes in the future!

For instance, in the above example, we saw that GetFeaturedListings was the name of the operation flagged with our breaking change. This operation queries for all of the Listing objects in Airlock, and is therefore concerned with the change we've just made to the Listing type. Even though we've approved and overridden the error that resulted from removing the Listing.photoInHexagonShape field, any new breaking changes introduced to the GetFeaturedListings operation will still be flagged in the future.

Similarly, if the Listings team makes another breaking change (like changing the return type for a field on Listing, or removing another of its fields entirely), they will encounter a new operation check failure.

With the override in place, we can rerun the check right here in Studio, by clicking Rerun check in the Checks page.

This time, the operation check will use the new configurations we've set on this operation, and our removal of the Listing.photoInHexagonShape field will no longer raise the alarm.

We can now run the same CI/CD process we detailed in the previous lesson to bring these schema changes into staging, then production.

Practice

Key takeaways

• Operation checks consider historical operations against the schema to ensure updates to a subgraph do not introduce breaking changes for clients.
• Errors that occur during an operation check can be overridden in Studio.
• Operation check overrides can be set on an operation-by-operation basis, enabling you to mark specific changes as approved or ignore an operation entirely.

Up next

We've introduced composition and operation checks to feel more confident in our changes to Airlock's schema. With these steps baked into the workflow, we've ensured that Airlock's developers can ship their changes without accidentally breaking something for another team or client.

In the next lesson, we'll see how we can enhance our insight into the graph by introducing usage reporting.