3. Updating entities
5m

Simplifying our entities

We've reviewed FlyBy's new features and seen everything our team is up against. There's one area in particular where we can make immediate improvements. We're using two entities, Location and Activity, between our three subgraphs. Each time we use an entity in a subgraph different from where we first defined it, we have historically used the extend keyword in conjunction with the @key and @external directives.

Past entity syntax between originating and extending subgraphs

Now that we've upgraded our gateway to use v2, however, we can shave off some of that syntax. To use an entity in another subgraph, we no longer need to use the extend keyword, and we can also omit the @external directive in most scenarios. Just by including the @key directive to denote an entity's primary key, our gateway server will be able to orchestrate requests between the subgraphs responsible for resolving each of the entity's fields.

Current entity syntax between originating and extending subgraphs

Let's start by updating the syntax for the Location entity we're using in the activities subgraph. In subgraph-activities/activities.graphql, complete the following:

Removing extra syntax

subgraph-activities/activities.graphql
type Location @key(fields: "id") {
id: ID!
"The activities associated with a location"
activities: [Activity]
}

Our locations subgraph doesn't use any entities we need to update, but the reviews schema file makes use of both the Activity and Location entities. Let's update those definitions by removing this extra syntax. In subgraph-reviews/reviews.graphql, complete the following:

Removing extra syntax from the reviews schema

subgraph-reviews/reviews.graphql
type Location implements Attraction @key(fields: "id") {
id: ID!
"The name of the attraction"
name: String! @external
"A short description about the attraction"
description: String! @external
"The attraction's main photo as a URL"
photo: String! @external
"The calculated overall rating based on all reviews"
overallRating: Float
"All submitted reviews for this attraction"
reviews: [Review]!
}
type Activity implements Attraction @key(fields: "id") {
id: ID!
"The name of the attraction"
name: String! @external
"A short description about the attraction"
description: String! @external
"The attraction's main photo as a URL"
photo: String! @external
"The calculated overall rating based on all reviews"
overallRating: Float
"All submitted reviews for this attraction"
reviews: [Review]!
}

Notice that we haven't yet removed the @external directive from the other fields that appear on the Location and Activity types in subgraph-reviews/reviews.graphql. We'll take care of this in the next lesson, when we discuss interfaces in Federation 2.

Note: In Apollo Federation 1, we applied the @external directive when including fields in an extending subgraph that are defined in the entity's originating subgraph. For the most part, we can omit the @external directive moving forward with v2. But when a subgraph uses the @requires or @provides directives in tandem with an entity's fields, the @external directive is still required. For more information, see the official documentation on the @requires and @provides directives.

Publishing subgraph updates

Now, let's publish the updates we've made to the activities and reviews subgraphs. To speed up our development, we'll use a script we've provided in the package.json file at the root of our project directory.

In a terminal in the root of the project, run the following command:

odyssey-voyage-I-lab
npm run publish

When we run this command, we'll first be prompted to provide our graph's APOLLO_GRAPH_REF variable (which includes the variant we're using: @current, for example). Then, the command will prompt us to provide the name of the subgraph to publish. When we provide activities, locations, or reviews as our subgraph name, the script will take care of the rest!

Note: Because we'll be making a lot of updates to our subgraphs throughout this lab, we've added this script to save time - but it's not a requirement! If you would prefer, feel free to type out the rover subgraph publish command manually, defining each one of the command variables based on the subgraph you're publishing.

Publishing subgraph updates

After the changes have been published, let's visit the Explorer in Studio and make sure that things are still running smoothly. We can use the below example query to test out our schema.

query GetLocationsAndActivitiesReviews {
locations {
name
reviews {
comment
}
activities {
name
reviews {
comment
}
}
}
}

With that, we've made a small update that has nevertheless improved the legibility of our subgraphs. Let's move on to FlyBy's shared types and explore the new flexibility Federation 2 offers us.

Key takeaways

  • Federation 2 cuts down on the amount of syntax needed to define entities in multiple subgraphs.
  • We can omit the extend keyword from the definition of an entity in another subgraph, and we no longer need to attach the @external directive to an entity's primary key field(s).
Previous
Next