Batching

Batching is the process of taking a group of requests, combining them into one, and making a single request with the same data that all of the other queries would have made. This is a way to reduce the number of requests that your application makes to the server.

The Batching functionality is described via the Batching RFC.

Enable Batching

Batching is disabled by default, but you can enable it by setting the batching option to true:

Disable batching

import { createYoga, createSchema } from 'graphql-yoga'
import { createServer } from 'node:http'
 
export const yoga = createYoga<ServerContext, UserContext>({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String!
      }
    `
  }),
  batching: false
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Execute batched operation

curl -X POST -H 'Content-Type: application/json' http://localhost:4000/graphql \
  -d '[{"query": "{ hee: hello }"}, {"query": "{ ho: hello }"}]'

Limit the amount of Batched Requests

By default up to 10 GraphQL requests are allowed within a single HTTP request. If this amount is exceeded an error will be raised. You can customize this option by passing an object to the batching configuration option:

Limit the amount of Batched Requests to 2

import { createYoga, createSchema } from 'graphql-yoga'
import { createServer } from 'node:http'
 
export const yoga = createYoga<ServerContext, UserContext>({
  schema: createSchema({
    typeDefs: /* GraphQL */ `
      type Query {
        hello: String!
      }
    `
  }),
  batching: {
    limit: 2
  }
})
 
const server = createServer(yoga)
server.listen(4000, () => {
  console.info('Server is running on http://localhost:4000/graphql')
})

Execute batched operation (exceed limit)

curl -X POST -H 'Content-Type: application/json' -i http://localhost:4000/graphql \
  -d '[{"query": "{ hee: hello }"}, {"query": "{ ho: hello }"}, {"query": "{ holla: hello }"}]'

When exceeding the batching limit the HTTP status code will be 413 (Payload Too Large).

GraphQL Error response

{
  "errors": [{ "message": "Batching is limited to 2 operations per request." }]
}

Last updated on November 15, 2022

Defer and Stream CORS