How Federation handles the N+1 query problem

GraphQL developers quickly encounter the infamous "N+1 query problem" with operations that return a list:

1
query TopReviews {
2
  topReviews(first: 10) {
3
    id
4
    rating
5
    product {
6
      name
7
      imageUrl
8
    }
9
  }
10
}

In a monolithic GraphQL server, the execution engine takes these steps:

1. Resolve the Query.topReviews field, which returns a list of Reviews.
2. For each Review in the list, resolve the Review.product field.

If the Query.topReviews field returns 10 reviews, then the executor resolves Review.product field 10 times. If the Reviews.product field makes a database or REST query for a single Product, then we'll see 10 unique calls to the data source. This is suboptimal for the following reasons:

• It's more efficient to fetch the 10 products in a single query (e.g. SELECT * FROM products WHERE id IN (<product ids>)).
• If any reviews refer to the same product, then we're wasting resources fetching something we already have.

The solution for monolithic GraphQL APIs is the dataloader pattern. All GraphQL server implementations support this pattern. The Apollo Server documentation explains how to use the JavaScript implementation in Node.js servers.

The N+1 problem in a federated graph

Consider the same TopReviews operation, but we've implemented the Review and Product types in separate subgraphs:

1
type Query {
2
  topReviews(first: Int): [Review]
3
}
4

5
type Review {
6
  id: ID
7
  rating: Int
8
  product: Product
9
}
10

11
type Product @key(fields: "id") {
12
  id: ID
13
}

1
type Product @key(fields: "id") {
2
  id: ID!
3
  name: String
4
  imageUrl: String
5
}

Fortunately, query planning handles N+1 queries for entities like the Product type by default! The query plan for this operation works like this:

1. First, we Fetch the list of Reviews from the Reviews subgraph using the root field Query.topReviews. We also ask for the id of each associated product.
2. Next, we extract the Product entity references and Fetch them in a batch to the Products subgraph's Query._entities root field.
3. After we get back the Product entities, we merge them into the list of Reviews, indicated by the Flatten step.

1
QueryPlan {
2
  Sequence {
3
    Fetch(service: "reviews") {
4
      {
5
        topReviews(first: 10) {
6
          id
7
          rating
8
          product {
9
            __typename
10
            id
11
          }
12
        }
13
      }
14
    },
15
    Flatten(path: "reviews.@") {
16
      Fetch(service: "products") {
17
        {
18
          ... on Product {
19
            __typename
20
            id
21
          }
22
        } =>
23
        {
24
          ... on Product {
25
            name
26
            imageUrl
27
          }
28
        }
29
      },
30
    },
31
  },
32
}

Writing efficient entity resolvers

In most subgraph implementations (including @apollo/subgraph), we don't write the Query._entities resolver directly. Instead, we use the reference resolver API for resolving an individual entity reference:

1
const resolvers = {
2
  Product: {
3
    __resolveReference(productRepresentation) {
4
      return fetchProductByID(productRepresentation.id);
5
    }
6
  }
7
};

The motivation for this API relates to a subtle, critical aspect of the subgraph specification: the order of resolved entities must match the order of the given entity references. If we return entities in the wrong order, those fields are merged with the wrong entities and we'll have incorrect results. To avoid this issue, most subgraph libraries handle entity order for you.

This does reintroduce the N+1 query problem: in the example above, we'll call fetchProductByID once for each entity reference.

Fortunately, the solution is exactly the same in a monolithic graph: dataloaders. In nearly every situation, reference resolvers should use a dataloader.

1
const resolvers = {
2
  Product: {
3
    __resolveReference(product, context) {
4
      return context.dataloaders.products(product.id);
5
    }
6
  }
7
};

Now, when the query planner calls the Products subgraph with a batch of Product entities, we'll make a single batched request to the Products data source.