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 (opens in a new tab).

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) (opens in a new tab).

GraphQL Error response

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

Defer and Stream CORS