11. Entities and the query plan


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

In this lesson, we will:

  • Learn how the router uses entities and the query plan to connect data from multiple subgraphs
  • Learn how entity representations and reference resolvers 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 query, 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 subgraphs.

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

So the starts the query plan with a request to the reviews subgraph.

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 query against the , and adding it to the query plan. The s for id, comment, rating and location all belong to the reviews subgraph.

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 subgraph (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 subgraphs.

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

Remember that entity representations are what the uses to track a specific object between subgraphs. 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 s from the reviews subgraph.

Illustration of an entity representation as a passport

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

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

With that, all the s in the query have been accounted for in the query plan. 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 subgraph.

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

The router sends an operation to the reviews subgraph

This subgraph 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 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 query plan! The next step is to retrieve the name from the locations subgraph.

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

Step 3: Querying the locations subgraph

Remember the _entities that showed up in our subgraph after we first defined an entity? 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 entity representations! This is where the entity representations that the received from the reviews subgraph will go.

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

The router uses the entities field

The sends this request to the location's subgraph.

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

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

The resolveReference resolver

The Location reference runs once for each entity representation in the query. 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 subgraph 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 subgraphs 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 router needs to query for fields from a different subgraph, it also asks for entity representations from the current subgraph it's querying. These representations will be used in the subsequent operation's _entities field, set as the value for the representations argument.
  • The reference resolver takes each representation and returns the matching data for its requested fields.

Up next

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