Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Docs
Start for Free

Query Plans

Learn how your router orchestrates operations across subgraphs


Learn about to help you debug advanced use cases of .

Whenever your receives an incoming , it needs to figure out how to use your to populate data for each of that operation's . To do this, the router generates a query plan:

Parallel
Fetch (reviews)
Fetch (users)
Fetch (hotels)
Flatten (latestReviews,[],hotel)

A is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single . Some of these operations depend on the results of other operations, so the query plan also defines any required ordering for their execution.

Example graph

Let's say our federated includes these subgraphs:

Hotels subgraph
type Hotel @key(fields: "id") {
id: ID!
address: String!
}
type Query {
hotels: [Hotel!]!
}
Reviews subgraph
type Hotel @key(fields: "id") {
id: ID! @external
reviews: [Review!]!
}
type Review {
id: ID!
rating: Int!
description: String!
}

Based on these subgraphs, clients can execute the following against our router:

query GetHotels {
hotels { # Resolved by Hotels subgraph
id
address
reviews { # Resolved by Reviews subgraph
rating
}
}
}

This query includes fields from both the Hotels subgraph and the Reviews subgraph. Therefore, the router needs to send at least one query to each subgraph to populate all requested fields.

Take a look at the router's query plan for this query:

This syntax probably looks confusing. 🤔 Let's break it down.

Structure of a query plan

A query plan is defined as a hierarchy of nodes that looks like a JSON or GraphQL when serialized.

At the top level of every query plan is the QueryPlan node:

QueryPlan {
...
}

Each node defined inside the QueryPlan node is one of the following:

NodeDescription
FetchTells the router to execute a particular operation on a particular subgraph.
ParallelTells the router that the node's immediate children can be executed in parallel.
SequenceTells the router that the node's immediate children must be executed serially in the order listed.
FlattenTells the router to merge the data returned by this node's child Fetch node with data previously returned in the current Sequence.
DeferTells the router about one or more blocks of @defered fields at the same level of nesting. The node contains a primary block and an array of deferred blocks.
Skip/IncludeTells the router to split a query plan into two possible paths that can change at runtime.

Each of these is described in further detail below.

Fetch node

A Fetch node tells the router to execute a particular GraphQL operation on a particular subgraph. Every query plan includes at least one Fetch node.

# Executes the query shown on the "books" subgraph
Fetch(service: "books") {
{
books {
title
author
}
}
},

The node's body is the operation to execute, and its service indicates which subgraph to execute the operation against.

In our example graph above, the following query requires data only from the Hotels subgraph:

query GetHotels {
hotels {
id
address
}
}

Because this operation doesn't require orchestrating operations across multiple subgraphs, the entire query plan contains just a single Fetch node:

QueryPlan {
Fetch(service: "hotels") {
{
hotels {
id
address
}
}
},
}

The Fetch node uses a special syntax when it's resolving a reference to an across subgraphs. For details, see Resolving references with Flatten.

Parallel node

A Parallel node tells the router that all of the node's immediate children can be executed in parallel. This node appears in query plans whenever the router can execute completely independent on different subgraphs.

Parallel {
Fetch(...) {
...
},
Fetch(...) {
...
},
...
}

For example, let's say our federated has a Books subgraph and a Movies subgraph. And let's say a client executes the following query to fetch separate lists of books and movies:

query GetBooksAndMovies {
books {
id
title
}
movies {
id
title
}
}

In this case, the data returned by each subgraph does not depend on the data returned by any other subgraph. Therefore, the router can query both subgraphs in parallel.

The query plan for the operation looks like this:

Sequence node

A Sequence node tells the router that the node's immediate children must be executed serially in the order listed.

Sequence {
Fetch(...) {
...
},
Flatten(...) {
Fetch(...) {
...
}
},
...
}

This node appears in query plans whenever one subgraph's response depends on data that first must be returned by another subgraph. This occurs most commonly when a query requests fields of an entity that are defined across multiple subgraphs.

As an example, we can return to the GetHotels query from our example graph:

query GetHotels {
hotels { # Resolved by Hotels subgraph
id
address
reviews { # Resolved by Reviews subgraph
rating
}
}
}

In our example graph, the Hotel type is an entity. Hotel.id and Hotel.address are resolved by the Hotels subgraph, but Hotel.reviews is resolved by the Reviews subgraph. And our Hotels subgraph needs to resolve first, because otherwise the Reviews subgraph doesn't know which hotels to return reviews for.

The query plan for the operation looks like this:

As shown, this query plan defines a Sequence that executes a Fetch on the Hotels subgraph before executing one on the Reviews subgraph. (We'll cover the Flatten node and the second Fetch's special syntax next.)

Flatten node

A Flatten node always appears inside a Sequence node, and it always contains a Fetch node. It tells the router to merge the data returned by its Fetch node with data that was previously Fetched during the current Sequence:

Flatten(path: "hotels.@") {
Fetch(service: "reviews") {
...
}
}

The Flatten node's path argument tells the router at what position to merge the newly returned data with the existing data. An @ element in a path indicates that the immediately preceding path element returns a list.

In the snippet above, the data returned by the Flatten's Fetch is added to the Sequence's existing data within the objects contained in the hotels list .

Expanded example

Once again, let's return to the GetHotels query on our example graph:

query GetHotels {
hotels { # Resolved by Hotels subgraph
id
address
reviews { # Resolved by Reviews subgraph
rating
}
}
}

The query plan for this operation first instructs the router to execute this query on the Hotels subgraph:

{
hotels {
id
address
__typename # The router requests this to resolve references (see below)
}
}

At this point, we still need review-related information for each hotel. The query plan next instructs the router to query the Reviews subgraph for a list of Hotel objects that each have this structure:

{
reviews {
rating
}
}

Now, the router needs to know how to merge these Hotel objects with the data it already fetched from the Hotels subgraph. The Flatten node's path argument tells it exactly that:

Flatten(path: "hotels.@") {
...
}

In other words, "Take the Hotel objects returned by the Reviews subgraph and merge them with the Hotel objects in the top-level hotels field returned by the first query."

When the router completes this merge, the resulting data exactly matches the structure of the client's original query:

{
hotels {
id
address
reviews {
rating
}
}
}

Resolving references with Flatten

Like Sequence nodes, Flatten nodes appear whenever one subgraph's response depends on data that first must be returned by another subgraph. This almost always involves resolving entity fields that are defined across multiple subgraphs.

In these situations, the Flatten node's Fetch needs to resolve a reference to an entity before fetching that entity's fields. When this is the case, the Fetch node uses a special syntax:

Flatten(path: "hotels.@") {
Fetch(service: "reviews") {
{
... on Hotel {
_typename
id
}
} =>
{
... on Hotel {
reviews {
rating
}
}
}
},
}

Instead of containing a GraphQL operation, this Fetch node contains two GraphQL , separated by =>.

  • The first is a representation of the entity being resolved (in this case, Hotel). Learn more about entity representations.
  • The second fragment contains the entity fields and subfields that the router needs the subgraph to resolve (in this case, Hotel.reviews and Review.rating).

When the router sees this special Fetch syntax, it knows to query a subgraph's Query._entities field. This field is what enables a subgraph to provide direct access to any available fields of an entity.

Now that you've learned about each query plan node, take another look at the example query plan in Example graph to see how these nodes work together in a complete query plan.

Defer node

A Defer node corresponds to one or more @defers at the same level of nesting in the query plan.

The node contains a primary block and an array of deferred blocks. The primary block represents the part of the query that isn't deferred. Each deferred block corresponds to the one deferred part of the query.

Read more about how @defer works in the router support for @defer article.

QueryPlan {
Defer {
Primary {
Fetch(...) {}
}, [
Deferred(...) {
Flatten(...) {
Fetch(...) {}
}
}
]
}
}

Condition nodes

A Skip or Include node splits a query plan into an if-else branch. Condition nodes are used when an operation contains a @skip or @include so the query plan can select different nodes based on the provided runtime .

QueryPlan {
Sequence {
Fetch(...) {}
Include(...) {
Flatten(...) {
Fetch(...) { }
}
}
}
}
QueryPlan {
Sequence {
Fetch(...) {}
Skip(...) {
Flatten(...) {
Fetch(...) { }
}
}
}
}

Viewing query plans

You can view the query plan for a particular operation in any of the following ways:

Outputting query plans with headers

With the Apollo Router Core v0.16.0+ and @apollo/gateway v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response :

  • Including the Apollo-Query-Plan-Experimental header returns the query plan in the response extensions
  • Additionally including the Apollo-Query-Plan-Experimental-Format header with one of the supported options changes the output format:
    • A value of prettified returns a human-readable string of the query plan
    • A value of internal returns a JSON representation of the query plan

Outputting query plans with @apollo/gateway

Your gateway can output the query plan for each incoming operation as it's calculated. To do so, add the following to the file where you initalize your ApolloGateway instance:

  1. Import the serializeQueryPlan function from the @apollo/query-planner library:

    const {serializeQueryPlan} = require('@apollo/query-planner');
  2. Add the experimental_didResolveQueryPlan option to the object you pass to your ApolloGateway constructor:

    const gateway = new ApolloGateway({
    experimental_didResolveQueryPlan: function(options) {
    if (options.requestContext.operationName !== 'IntrospectionQuery') {
    console.log(serializeQueryPlan(options.queryPlan));
    }
    }
    });

    The value you provide for this option is a function that's called every time the gateway generates a query plan. The example function above logs the generated query plan for every operation except for queries (such as those sent periodically by tools like the ). You can define any logic you want to log query plans or otherwise interact with them.

    For all available options passed to your function, see the source.

Previous
Monitoring
Next
Error Codes
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy

Company