11. Entities and the query plan


We've set up our definitions, but how exactly does the use these entities?

In this lesson, we will:

  • Learn how the uses entities and the to connect data from multiple s
  • Learn how representations and reference work together

Let's look at an example query

Let's say the client makes a request for our app's latest reviews. In their , they'll request the id, comment, and rating for each review, along with the name of each review's location.

query GetLatestReviews {
latestReviews {
location {
Client sends a request to the router

Now it's the 's time to shine!

Step 1: Building the query plan

Like we saw earlier, the begins by building a query plan that indicates which requests to send to which .

The starts with the incoming 's top-level , latestReviews. With the help of the , the sees that latestReviews is defined in the reviews .

So the starts the with a request to the reviews .

The router uses the supergraph schema to build a query plan, starting with the reviews subgraph

The continues like this for a while, checking each in the against the , and adding it to the . The fields for id, comment, rating and location all belong to the reviews .

The router continues to build the query plan

But when the reaches the name for a particular Location, it sees from the that Location.name can only be resolved by the locations (because that's where the Location.name is defined).

The router sees that Location.name belongs to the locations subgraph

That means the is going to have to connect data between .

To do this, the needs some more information from the reviews : the representation for each review's corresponding Location object.

Remember that representations are what the uses to track a specific object between . To make an entity representation for a Location object, the needs the location's typename and its primary key (which in this case is the id ).

Illustration of an entity representation as a passport

The can get both these from the reviews .

Illustration of an entity representation as a passport

From there, the adds another to its to request the location's name from the locations .

The router adds a query for location name to the query plan

With that, all the in the have been accounted for in the . It's time to move on to the next step: executing the plan.

Step 2: Querying the reviews subgraph

The begins by requesting data from the reviews .

The reviews resolves all the requested as it normally would, including the representations for all the requested location objects.

The router sends an operation to the reviews subgraph

This doesn't know that the plans to do anything special with the location's id or typename. It just sends back the data to the router like it was asked.

The reviews subgraph sends back the data to the router

With that, the 's taken care of the first part of the ! The next step is to retrieve the name from the locations .

Next up on the query plan, the location's name

Step 3: Querying the locations subgraph

Remember the _entities that showed up in our after we first defined an ? This is where it comes back into the story!

The builds a request using the _entities .

This takes in an called representations, which takes in, well, a list of representations! This is where the entity representations that the received from the reviews will go.

In the same request, the adds the rest of the left in the (in this case, the location's name).

The router uses the entities field

The sends this request to the location's .

To resolve the _entities , the locations uses its reference resolver. Remember this is a special function used to return all the that this contributes.

The locations looks at the __typename value of each reference object to determine which 's reference to use. In this case, because typename is "Location", the locations knows to use the Location 's reference .

The resolveReference resolver

The Location reference runs once for each representation in the . Each time, it uses the entity representation's primary key to return the corresponding Location object.

The Location reference resolver resolves each entity representation using the primary key

After the locations finishes resolving the request, it sends the data back to the .

Locations subgraph returns data to the router

That's it for the executing phase!

Step 4: Sending the final response to the client

Now, the combines all the data it received from the reviews and locations into a single JSON object. And at last, the sends the final object back to the client.

The router finally returns data to the client


Which of the following steps do NOT occur as part of how the router builds and executes its query plan?

Key takeaways

  • When the needs to for from a different , it also asks for representations from the current subgraph it's querying. These representations will be used in the subsequent 's _entities , set as the value for the representations .
  • The reference takes each representation and returns the matching data for its requested .

Up next

Now we know exactly what is happening in a 's and how the pieces fit together! In the next lesson, we'll dive into the code and start with referencing an from a .


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.