10. Defining an entity
3m

Overview

Let's jump into the code!

In this lesson, we will:

  • Convert the Location type into an entity that can be shared between our subgraphs
  • Publish updates to existing subgraphs

✏️ Defining the Location entity's @key

  1. Open up the subgraph-locations/locations.graphql file and find the Location type.

    subgraph-locations/locations.graphql
    type Location {
    id: ID!
    "The name of the location"
    name: String!
    "A short description about the location"
    description: String!
    "The location's main photo as a URL"
    photo: String!
    }
  2. We'll add the @key to this type definition, specifying the fields property and setting its value to id.

    subgraph-locations/locations.graphql
    type Location @key(fields: "id") {
    id: ID!
    "The name of the location"
    name: String!
    "A short description about the location"
    description: String!
    "The location's main photo as a URL"
    photo: String!
    }

Check changes in Sandbox

Let's test our changes. Open up http://localhost:4001 in your browser and use Sandbox to query our server again.

In the Documentation tab, we should now see that there's a new on the Query type called _entities. This is a special that the uses for coordinating data between subgraphs. We'll learn how exactly the uses this in the next lesson.

studio.apollographql.com/sandbox/explorer
The Location subgraph displaying an _entities field

Other than that, not much has changed! We should still be able to use to query the locations subgraph as before. (Try running a quick query for some data on the locations , to make sure everything still works as expected.)

Publish the locations subgraph

We'll need to publish this subgraph so that the can pick up our changes.

Let's make sure we're in the top-level directory of our project when we run the rover subgraph publish command in the terminal.

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

We can omit the --routing-url option in the command because we already set that value the first time we published the subgraph to the .

Great, it looks like our changes have been published successfully!

✏️ Defining our entity in reviews

We want to use the Location entity in our reviews subgraph as well.

  1. Open up the subgraph-reviews/reviews.graphql file.

  2. We'll add the Location type definition, along with the @key and set the id as the primary key.

    subgraph-reviews/reviews.graphql
    type Location @key(fields: "id") {
    # to fill in
    }
  3. Inside the curly braces, we'll add the id of type non-nullable ID!.

    subgraph-reviews/reviews.graphql
    type Location @key(fields: "id") {
    id: ID!
    }

    The Location entity doesn't need to include all the s we defined for it in the locations subgraph. After all, the reviews subgraph doesn't know anything about these s, or how to resolve them!

    So far, we've given our reviews subgraph a stub of the Location entity. A stub serves as a basic representation of a type that includes just enough information to work with that type in the subgraph.

    There's one more change we need to make. Because the reviews subgraph is not responsible for resolving any of the entity's other s, we'll add one more property to our @key .

  4. Inside the @key , add a property called resolvable and set it to false.

    subgraph-reviews/reviews.graphql
    type Location @key(fields: "id", resolvable: false) {
    id: ID!
    }

    This property tells the that this subgraph doesn't define a reference for this entity.

    Recall that a reference is responsible for returning all of the entity s that this subgraph contributes. The reviews subgraph doesn't contribute any other s (besides the key ), so it doesn't need to define a reference . The resolvable: false property indicates this to the !

Publish the reviews subgraph

Now let's publish our reviews subgraph updates. From a terminal in the root directory of our project, let's run the rover subgraph publish command again.

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

Alright, we see a success message and our changes have made it to the !

Practice

Code Challenge!

Convert the Book type below into an entity. A Book can be uniquely identified by its International Standard Book Number (ISBN).

Key takeaways

  • To create an entity, we can use the @key directive to specify which field(s) can uniquely identify an object of that type.
  • When a subgraph can't be used to resolve any non-@key fields of an entity, we pass resolvable: false to the @key directive definition.

Up next

We've added entities to our subgraph s and published our changes!

In the next lesson, we'll learn how the uses entities and entity representations to connect data from multiple subgraphs.

Previous
Next