8. Publishing our schemas
6m

Overview

We're well on our way with the accounts subgraph! We've defined our User interface and the Host and Guest entities in both subgraphs. It's time to get these changes composed into the supergraph!

In this lesson, we will:

  • Learn about how fields can (and cannot) be shared between subgraphs
  • Publish our changes to the registry and test our updated supergraph

Publishing our schema changes

We've made a lot of changes to our two subgraph schemas. Let's check to see if our supergraph schema still composes.

Note: We're going to publish our current subgraph schemas to the registry, which will take care of composition for us. However, when working in a production environment, you'll want to first test these schema changes using a combination of schema checks and variants integrated into your CI pipeline. We'll dive into these concepts in Voyage III, the next course of the series.

To publish our schema changes in the accounts subgraph, we'll use the rover subgraph publish command with the corresponding values. Since this is the first time we're publishing the accounts subgraph, we'll also need to add a routing-url.

rover subgraph publish <APOLLO_GRAPH_REF> \
--schema ./subgraph-accounts/schema.graphql \
--name accounts \
--routing-url http://localhost:4002

Remember to replace the <APOLLO_GRAPH_REF> value with your own, and take note that we're running this command in the root directory of our project!

Wait - what are these errors in the terminal? Here's an example of one of the errors we see after running the command.

INVALID_FIELD_SHARING: Non-shareable field "Host.name" is resolved from multiple subgraphs:
it is resolved from subgraphs "accounts" and "monolith" and defined as non-shareable in all of them

What we're seeing is an example of invalid field sharing.

Invalid field sharing

Let's talk about what this error means, and what we can do to fix it!

We published our accounts schema to Studio, which triggered composition. But right now, the latest version of the monolith subgraph that Studio is aware of is the one without our most recent changes. As far as it knows, the monolith subgraph still includes these accounts-related fields on Host and Guest!

As a result, the composition process discovered a number of fields that are defined in both of the subgraphs Studio knows about. This causes an error because by default, a field can't be defined or resolved by more than one subgraph.

If we did want a field to be defined or resolved by multiple subgraphs, we'd need to enable this explicitly by using the @shareable directive.

The @shareable directive

The @shareable directive enables multiple subgraphs to resolve a particular object field (or set of object fields).

For example, if we wanted to allow both the monolith and accounts subgraphs to resolve the Host.name field, we could leave the definitions in both and mark the field with @shareable.

type Host implements User @key(fields: "id") {
# ... other Host fields
name: String @shareable
}

Note: You'd also need to add the @shareable directive to the Federation 2 schema definition imports in the subgraph, as detailed in the docs.

Adding the @shareable directive to both field definitions would take care of the build error.

However, in our case, we don't want to do this! For Airlock, we've decided that only the accounts subgraph will be responsible for these fields. Fortunately, we can fix this error by publishing our changes to the monolith subgraph. This will bring Studio up to date on our decision to relocate accounts-related fields to the accounts subgraph.

Publishing the monolith subgraph

Let's take care of this step now, and clear up those errors in the terminal! Run the following rover subgraph publish command for the monolith subgraph, swapping in the values specific to your graph.

rover subgraph publish <APOLLO_GRAPH_REF> \
--schema ./monolith/schema.graphql \
--name monolith

With that, we should see that the composition process was successful! Studio is now up to speed on how we've decided to divide fields between our subgraph schemas.

The 'monolith' subgraph for the <APOLLO_GRAPH_REF> graph was updated
The gateway for the <APOLLO_GRAPH_REF> graph was updated with a new schema, composed from the updated 'monolith' subgraph

Testing our schema changes

Let's check the results in our graph on Apollo Studio. Navigate to the Schema page and the SDL tab. We'll see a new subgraph on this list called accounts! 🎉

Next up, we'll put these changes to the test. Head over to the Explorer and run this query:

query GetMyProfile {
me {
id
name
profilePicture
}
}

Make sure your Headers are set to:

Authorization: Bearer user-1

When you run the query... uh-oh! We get a new error: Cannot return null for non-nullable field Host.name.

That's because we have yet to move the corresponding resolvers over to the accounts subgraph! (And we'll need to move that me entry point over as well.) Let's take care of the resolvers first, in the next lesson.

Practice

In which of the following scenarios should the @shareable directive be used?

Key takeaways

  • The INVALID_FIELD_SHARING error occurs when multiple subgraphs implement the same object type field without designating it as shareable.
  • Applying the @shareable directive enables multiple subgraphs to resolve a particular object field (or set of object fields). This allows the field(s) to which the directive is applied to exist in more than one subgraph.

Up next

We don't have any resolvers set up in the accounts subgraph, so we aren't getting any data back about users! Let's tackle that next.

Previous
Next