GraphQL Batching and the DataLoader Pattern in Magento 2

1. How the N+1 problem arises in Magento GraphQL

The N+1 problem is the most common performance trap in every GraphQL layer, including Magento's. It occurs when a query returns a list of objects, for example products in a cart, and a nested resolver triggers its own database or API query for every single object. With ten cart items, that means one query for the list plus ten more individual queries, eleven total instead of a single efficient query. On extensive storefront queries with several nested levels, the N+1 problem can multiply and push response times into the range of several seconds.

In Magento, the problem typically shows up on custom fields on products that need additional repository calls, for example availability data from an external warehouse management system or individual price rules per customer. A naively written resolver calls the service separately for every product in the list, without knowing that ten or twenty other products in the same request are being processed the same way. GraphQL batching solves exactly this problem by collecting all individual requests within one request and processing them together.

The mistake often lies in looking at a resolver in isolation, without considering the context of the entire query tree. GraphQL executes resolver functions per field and per object in a list separately, the framework itself does not batch anything automatically. Without explicit batching, the responsibility for efficient data fetching stays entirely with the developer of the resolver class.

2. The DataLoader pattern explained

The DataLoader pattern, originally known from the JavaScript ecosystem around Facebook's GraphQL reference implementation, solves the N+1 problem through two mechanisms: batching and caching within a single request. Instead of executing a request immediately, a DataLoader collects all requests arriving within one processing cycle in a queue. Only at the end of this cycle is a single batch function called with all collected keys, for example every product ID requested in the current request.

Magento adapts this DataLoader pattern not as an external library but through its own interface in the GraphQl framework: BatchResolverInterface. Instead of a single resolve() method, a batch resolver implements the method resolve(BatchRequestItemInterface ...$requests), which is called with all individual requests collected in the current request. Magento's query executor automatically collects these requests across all objects in a list and only calls the batch method once all individual requests are known.

# app/code/Mironsoft/StockAvailability/etc/schema.graphqls
# Custom field resolved via batching to avoid N+1 queries

type ProductInterface {
    external_stock_status: String
        @resolver(class: "Mironsoft\\StockAvailability\\Model\\Resolver\\ExternalStockStatus")
        @doc(description: "Live stock status fetched from the external warehouse system")
}

3. Using BatchResolverInterface in Magento

The central class for GraphQL batching in Magento is Magento\Framework\GraphQl\Query\Resolver\BatchResolverInterface from the Magento_GraphQl module. It was introduced to fix exactly the weakness of the classic ResolverInterface described in the previous section. While ResolverInterface::resolve() is called separately per field and per object, BatchResolverInterface collects all requests and hands them over bundled to a single method.

Every individual request in this batch is a BatchRequestItemInterface object that provides access to the parent object, the GraphQL arguments and the context. The resolver iterates once over all requests to extract the required keys, then executes exactly one bulk call against the repository or the external service, and afterwards distributes the results back to the individual requests. This structure is the core of every efficient batch resolver in Magento.

4. Implementing your own batch resolver

Implementing a custom batch resolver follows a fixed flow: collect keys from all requests, execute one bulk call, map results into an associative array by key, and return the matching result for every individual request through AggregateFactory. It is important that missing results are also handled cleanly, for example when a product has no external stock status, so that the query does not abort with an error but returns null for that one field.

The example resolver below fetches the external stock status for a list of products in a single call, instead of sending an individual HTTP request for every product. With 20 products in a query, that means a single bulk request instead of 20 individual requests, a difference that shows up directly in response time on every category page with many products.

<?php
declare(strict_types=1);

namespace Mironsoft\StockAvailability\Model\Resolver;

use Magento\Framework\GraphQl\Query\Resolver\BatchRequestItemInterface;
use Magento\Framework\GraphQl\Query\Resolver\BatchResolverInterface;
use Magento\Framework\GraphQl\Query\Resolver\Result\AggregateFactory;
use Magento\Framework\GraphQl\Query\Resolver\Result\ResolverResult;
use Mironsoft\StockAvailability\Api\ExternalStockGatewayInterface;

/**
 * Batch resolver for external_stock_status field on ProductInterface.
 * Collects all requested SKUs and performs a single bulk gateway call.
 */
final class ExternalStockStatus implements BatchResolverInterface
{
    /**
     * @param ExternalStockGatewayInterface $stockGateway Bulk-capable stock gateway client
     * @param AggregateFactory $aggregateFactory Factory to build the aggregate resolver result
     */
    public function __construct(
        private readonly ExternalStockGatewayInterface $stockGateway,
        private readonly AggregateFactory $aggregateFactory
    ) {
    }

    /**
     * Resolve external_stock_status for a batch of products in a single call.
     *
     * @param BatchRequestItemInterface[] $requests
     * @return \Magento\Framework\GraphQl\Query\Resolver\BatchResolverInterface\BatchResponse
     */
    public function resolve(array $requests): iterable
    {
        // Collect all SKUs from the batch — no gateway call yet
        $skus = [];
        foreach ($requests as $request) {
            $product = $request->getValue()['model'];
            $skus[] = $product->getSku();
        }

        // Single bulk call for the entire batch instead of one call per product
        $statusMap = $this->stockGateway->getStatusForSkus(array_unique($skus));

        $response = $this->aggregateFactory->create();
        foreach ($requests as $request) {
            $product = $request->getValue()['model'];
            $status = $statusMap[$product->getSku()] ?? null;
            $response->addResponse($request, new ResolverResult($status));
        }

        return $response;
    }
}

5. Repository aggregation for batch requests

For a batch resolver to actually be efficient, the underlying repository or gateway method itself must offer a bulk signature that processes several keys at once. A repository that still internally executes individual calls in a loop just pushes the N+1 problem one level down without solving it. For database queries, that means a WHERE sku IN (...) instead of multiple WHERE sku = ? calls. For external APIs, that means a bulk endpoint accepting a list of identifiers instead of one endpoint per individual object.

For repositories that, for historical reasons, have no bulk method, it is worth adding an aggregation layer that parallelizes several individual calls instead of processing them sequentially. This is not a full replacement for genuine batching, but it at least reduces the total runtime when a real bulk API is unavailable. In the long run, every repository method used frequently in list contexts should receive a bulk variant.

6. Request level cache for repeated access

Besides pure batching, the DataLoader pattern brings a second mechanism: caching within a single request. If the same key is requested multiple times within the same query, for example because a product appears both in the main list and in a cross sell section, the DataLoader returns the already loaded result from the request cache instead of triggering a second batch request. This cache lives exclusively for the duration of one single GraphQL request and is discarded afterwards, unlike the persistent full page cache.

In Magento, this behavior can be replicated with a simple in memory array per resolver instance, injected through the constructor or kept as a private property. It is important not to confuse this request cache with the framework wide cache: it serves only for deduplication within a single request, not for persistence across multiple requests. For requests with heavily overlapping object graphs, this mechanism can save noticeable additional resources on top of batching.

7. Measuring performance: before and after

Without measurement, any claim about the benefit of GraphQL batching remains speculation. Magento's developer mode does show cache information in the X-Magento-Tags response header, but no query counters. For analyzing actual database load, the built in profiler (Magento\Framework\Profiler) combined with a tool such as Blackfire or Xdebug that counts SQL queries per request is suitable. A naive resolver for a list of 30 products typically shows 30 additional individual queries here, a correctly implemented batch resolver reduces that to a single one.

In practice, it is worth running a simple load test with a realistic query that combines nested fields with many list items, for example a category query with 50 products and a batched custom field per product. The difference between a naive and a batched implementation usually shows up clearly in response time under load, while it is barely noticeable on a single, unloaded request. This is precisely why the problem is often overlooked in local development and only becomes visible in production with real catalog sizes.

8. Limits and pitfalls of batching

GraphQL batching is not a cure all. If the underlying data source itself does not support bulk operations, for example a legacy API with only single object endpoints, a batch resolver in Magento at best parallelizes the individual calls but does not truly reduce the number of requests. A second pitfall concerns error handling: if the bulk call fails for a single invalid ID, that must not crash the entire batch response, it needs to be cleanly mapped to null or an error value per request instead.

A third point concerns complexity: batch resolvers are harder to debug than simple ResolverInterface implementations, because the execution order no longer runs linearly per object but happens bundled only at the end of a collection cycle. For fields that rarely appear in lists or are already performant, for example attributes already present on the product object, the additional implementation effort of a batch resolver often is not worth it. The decision should be based on actually measured query counts, not on a blanket rule.

9. Naive resolver vs. batch resolver compared

The following table compares both approaches based on concrete criteria to make the decision for a project easier.

For fields with low call frequency or without a genuine bulk data source, the naive resolver often remains the more pragmatic choice. As soon as a field regularly appears in lists with more than a few elements, the advantage of the batch resolver clearly outweighs the extra effort, especially on heavily trafficked category and search pages.

10. Summary

GraphQL batching following the DataLoader pattern is the direct answer to the N+1 problem in nested Magento queries. Instead of sending a separate query per list item, BatchResolverInterface collects all requests of a request and resolves them with a single bulk call. This requires a repository or gateway method that can genuinely process several keys at once, otherwise the problem is only pushed one level down.

Request level caching complements batching with deduplication for objects referenced multiple times within the same query. The effort of building a custom batch resolver pays off especially for fields that regularly appear in large lists, for example on category pages with many products. For rare or already performant fields, the classic, easier to maintain resolver often remains the better choice, decided based on actual query measurements rather than assumptions.

11. FAQ: GraphQL Batching and DataLoader Pattern in Magento 2