Data loaders under the hood

3. Data loaders under the hood

10m

Overview

In this lesson, we will:

Discuss what a data loader is
Introduce the dataloader package
Review the requirements of a data loader
Walk through how a data loader works under the hood

Data loaders

To solve the n+1 problem in our application, we'll use data loaders.

A data loader's primary job is to replace multiple similar requests with a single batched request. In our example, we saw three near-identical requests that used a particular listing ID to return amenity data. With a data loader, this becomes a single request that fetches data for all three listings at once.

We'll bring the power of data loaders into our data source class using the GraphQL dataloader package.

The `dataloader` package

The dataloader package is a utility that provides batching and caching capabilities. This lets us batch together various keys in a single request—serving up all the data, all at once!

Let's illustrate this with the following query.

A query for featured listings and their amenities

query GetFeaturedListingsAmenities {
  featuredListings {
    id
    title
    amenities {
      id
      name
      category
    }
  }
}

For each featured listing object this query resolves, the Listing.amenities resolver will be invoked. Currently, this resolver uses a listing's ID to resolve each request independently. (That's what results in three separate network requests to the same endpoint!)

The behavior we want is quite different: we want the data loader to collect all the listing IDs involved in the query (also called keys), and execute a single request.

In our example, this means that when the Listing.amenities resolver is called using each listing's ID, it won't call the ListingAPI's method that hits our REST API directly; instead, it will pass each key to a data loader method, which can batch together all the keys needed for the entire operation.

Once the individual listing IDs are gathered in one list, the data loader can assume the responsibility of actually requesting data from the data source. It's able to dispatch a single request to the REST API endpoint for all of the IDs at once—a huge performance boost over letting the resolver initiate a network request for each!

Best of all, our data loader method will automatically deduplicate the identifiers we pass them. This means if our query included multiple listings with the same ID, we'll only request the listing's amenities once.

What a data loader needs

Data loaders are exactly what we need to solve the performance issues in our app—but they come with a few requirements for us to consider. Let's walk through each of these one by one.

Data for multiple objects at once

Let's imagine our data loader has collected all of the different keys involved in our query, and it's ready to fire off a request for data. What does it need next?

Well, if we think about the REST API endpoint we've used previously to return amenity data, we'll quickly see the problem: right now, the Listing.amenities resolver relies on the ListingAPI method getAmenities to send each listing ID individually to the GET /listings/{listing_id}/amenities endpoint, which only returns data for a single listing.

That brings us to the first big requirement for a data loader to work as expected: we need a data source that can resolve a request for multiple objects simultaneously. In practice, this means that our data loader should be able to send off a list of keys (such as ["listing-1", "listing-2", "listing-3"]) and get back data for all of them.

The good news is that we do have a different endpoint in our REST API that we can use to request amenity data for multiple listings: GET /amenities/listings. It accepts multiple listing IDs joined as a single query parameter string called ids, and returns data for them all at once.

A REST endpoint that receives multiple keys, and returns multiple values

GET /amenities/listings?ids=listing-1,listing-2,listing-3

For every key, a value

When a data loader sends off a list of keys in a request, it has a very clear expectation from the data source providing the data: the number of objects returned should never be greater than the number of keys that were sent in the request. The values returned should also be in the same order as the corresponding keys that were requested.

Let's break down this expectation and how the data source satisfies it.

In the process of resolving a query, our resolver might call the data loader three times, passing it three keys. The data loader groups them together into one list (["listing-1", "listing-2", "listing-3"]), then calls the GET /amenities/listings with them. What does it expect back? Well, it put in a list of three keys; it expects a list of no more than three objects back!

A diagram showing a request with three listing IDs; three lists of amenities are returned

For each key requested, we expect our data source to return a list of amenities. This is because each listing can have more than one amenity associated with it. If we request amenity data for three listing ids, therefore, our response should consist of three lists of amenities.

A diagram showing three listing IDs; and three lists of amenities that map to them

Note: The data loader also expects each object returned to align with the position of its corresponding key in the original request. For instance, if "listing-1" was sent as the first key, its list of amenities should be the first object in the response!

From there, the data loader handles the logic of mapping each list of amenities back to the key that requested it.

When we request featured listings data, each object contains an amenities key, which is an array of amenity IDs.

An example listing object in the featured listings JSON response


{
  "id": "listing-1",
  "title": "Cave campsite in snowy MoundiiX",
  "description": "Enjoy this amazing cave campsite in snow MoundiiX, where you'll be one with the nature and wildlife in this wintery planet. All space survival amenities are available. We have complementary dehydrated wine upon your arrival. Check in between 34:00 and 72:00. The nearest village is 3AU away, so please plan accordingly. Recommended for extreme outdoor adventurers.",
  "costPerNight": 120,
  // ... other properties
  "amenities": [
    {
      "id": "am-2"
    },
    {
      "id": "am-10"
    },
    {
      "id": "am-11"
    },
    {
      "id": "am-12"
    },
    {
      "id": "am-13"
    },
    {
      "id": "am-26"
    },
    {
      "id": "am-27"
    },
    {
      "id": "am-16"
    }
  ]
}

This means that we have two possible ways to request follow-up amenity data for a given listing: we could use the listing ID to send a request to the GET /amenities/listings endpoint, as we're about to do, or we could gather up all of the amenity IDs in a listing's amenities property, and make one big request for amenity data to the GET /amenities endpoint.

Let's use our GetFeaturedListingsAmenities query to walk through what this second option (requesting amenities by amenity IDs) would have looked like.

A query for featured listings and their amenities


query GetFeaturedListingsAmenities {
  featuredListings {
    id
    title
    amenities {
      name
    }
  }
}

For every listing object returned, the Listing.amenities resolver would be executed. Here, we could access a particular listing's amenities field, map through all the amenity IDs, and pass the whole list to the data loader to be batched together.

Even with just three listing objects in our featured listings response, this starts to look a bit more complicated: the data loader collects each listing's list of amenity IDs, gathering them up in one larger list.

Here's the big problem with this approach. Each entire list of amenities we pass into the data loader is considered a key.

So if we have two lists contain some of the same amenity IDs, we won't enjoy the benefit of data loader deduplication here; it's looking at each list of amenity IDs as a whole.

Even if the ListingAPI held the logic to break apart each list of amenity IDs, deduplicate them, and make one big request to the GET /amenities endpoint, we'll see another problem emerge.

Now we get back one big blob of amenity data; it's not immediately clear how to map this response back to the list of keys the data loader dispatched the request with. Simply returning the whole blob for the resolver to deal with doesn't work either; the data loader tries to enforce that we get a number of objects less than or equal to the number of keys that we submitted. So three keys in should mean, at most, three objects out.

Consequently, we'd need to introduce another layer of logic in the ListingAPI to receive the JSON results, map through them, and match up each list of amenity IDs with the corresponding data.

It's because of this complication that we've chosen to use a listing's id field to fetch its amenities: it's a lot cleaner, and it allows the data loader to do most of the work!

Data loader scope

There's one last important point to keep in mind. Data loaders and the set of keys they process at any one time should be limited to a single request. Accordingly, our implementation in the next lesson will ensure that a new DataLoader instance is created per request.

This means that if we run one query for listing data, then a second query, the keys from both queries will NOT be batched together. Instead, each query will be resolved separately.

A diagram demonstrating how a data loader handles two queries separately

With these conceptual points cleared up, let's turn our attention back to the code. We'll update our Listing.amenities resolver to call a new method in our ListingAPI class—and benefit from the power of a data loader!

Practice

Which of the following statements about data loaders is true?

A data loader will wait until ALL queries have run before batching all requests together.A data loader replaces multiple similar requests with a single batched request.Data loaders can solve the n+1 problem by reducing the number of calls our GraphQL API makes for extra data.A data loader replaces our application's resolvers.

Key takeaways

Data loaders let us batch a list of identifiers (such as IDs) in a single request rather than sending an individual request for each.
Before data loaders can work properly, our data source (whether another API, or a database) needs to implement a method that accepts multiple keys (such as IDs), and returns multiple objects.
The number of objects a data loader receives from a data source should not exceed the number of keys the data loader collected. (For instance, if a data loader requests data for three listings, it should receive no more than three listing objects back!)

Up next

We've learned about data loaders and the problem that they solve in our application. We also have a new data source method that accepts multiple listing IDs, and resolves multiple amenity objects. Next up, we'll implement the data loader logic that gathers up multiple listing IDs in a single request.

Share your questions and comments about this lesson

This course is currently in

beta

. 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.