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 s
  • Publish updates to existing s

✏️ 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 s. We'll learn how exactly the router uses this field 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 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 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 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 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 . After all, the reviews doesn't know anything about these s, or how to resolve them!

    So far, we've given our reviews 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 .

    There's one more change we need to make. Because the reviews 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 doesn't define a reference for this entity.

    Recall that a reference is responsible for returning all of the entity s that this contributes. The reviews doesn't contribute any other s (besides the key field), 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 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 to specify which (s) can uniquely identify an object of that type.
  • When a can't be used to resolve any non-@key s of an entity, we pass resolvable: false to the @key definition.

Up next

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

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

Previous
Next

Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.