Query batching

Receive query batches with the Apollo Router

This feature is experimental. Your questions and feedback are highly valued—don't hesitate to get in touch with your Apollo contact or on the official Apollo GraphQL Discord.

Learn about query batching and how to configure the Apollo Router to receive query batches.

About query batching

Modern applications often require several requests to render a single page. This is usually the result of a component-based architecture where individual micro-frontends (MFE) make requests separately to fetch data relevant to them. Not only does this cause a performance overhead—different components may be requesting the same data—it can also cause a consistency issue. To combat this, MFE-based UIs batch multiple client operations, issued close together, into a single HTTP request. This is supported in Apollo Client and Apollo Server.

The Apollo Router supports client query batching. If you’re using Apollo Client, you can leverage the built-in support for batching to reduce the number of individual operations sent to the router.

Once configured, Apollo Client automatically combines multiple operations into a single HTTP request. The number of operations within a batch is client-configurable, including the maximum number in a batch and the maximum duration to wait for operations to accumulate before sending the batch.

The Apollo Router must be configured to receive query batches, otherwise it rejects them. When processing a batch, the router deserializes and processes each operation of a batch independently, and it responds to the client only after all operations of the batch have been completed. Each operation executes concurrently with respect to other operations in the batch.

Configure query batching

Both the Apollo Router and client need to be configured to support query batching.

Configure router

By default, receiving client query batches is not enabled in the Apollo Router.

To enable query batching, set the following fields in your router.yaml configuration file:

router.yaml

1
experimental_batching:
2
  enabled: true
3
  mode: batch_http_link

Attribute	Description	Valid Values	Default Value
`enabled`	Flag to enable reception of client query batches	boolean	`false`
`mode`	Supported client batching mode	`batch_http_link`: the client uses Apollo Link and its `BatchHttpLink` link.	No Default

Configure client

To enable batching in an Apollo client, configure BatchHttpLink. For details on implementing BatchHttpLink, see batching operations.

Configuration compatibility

If the router receives a query batch from a client, and batching is not enabled, the router sends a BATCHING_NOT_ENABLED error to the client.

Metrics for query batching

Metrics in the Apollo Router for query batching:

Name	Attributes	Description
`apollo.router.operations.batching`	mode	Counter for the number of received batches.
`apollo.router.operations.batching.size`	mode	Histogram for the size of received batches.

Query batch formats

Request format

A query batch is an array of operations.

1
[
2
query MyFirstQuery {
3
  me {
4
    id
5
  }
6
},
7
query MySecondQuery {
8
  me {
9
    name
10
  }
11
}
12
]

Response format

Responses are provided in JSON array, with the order of responses matching the order of operations in the query batch.

1
[
2
  {"data":{"me":{"id":"1"}}},
3
  {"data":{"me":{"name":"Ada Lovelace"}}}
4
]

Error handling for query batching

Batch error

If a batch of queries cannot be processed, the entire batch fails.

For example, this batch request is invalid because it has two commas to separate the constituent queries:

1
[
2
query MyFirstQuery {
3
  me {
4
    id
5
  }
6
},,
7
query MySecondQuery {
8
  me {
9
    name
10
  }
11
}
12
]

As a result, the router returns an invalid batch error:

1
{"errors":
2
  [
3
    {"message":"Invalid GraphQL request","extensions":{"details":"failed to deserialize the request body into JSON: expected value at line 1 column 54","code":"INVALID_GRAPHQL_REQUEST"}}
4
  ]
5
}

Individual query error

If a single query in a batch cannot be processed, this results in an individual error.

For example, the query MyFirstQuery is accessing a field that doesn't exist, while the rest of the batch query is valid.

1
[
2
query MyFirstQuery {
3
  me {
4
    thisfielddoesnotexist
5
  }
6
},
7
query MySecondQuery {
8
  me {
9
    name
10
  }
11
}
12
]

As a result, an error is returned for the individual invalid query and the other (valid) query returns a response.

1
[
2
  {"errors":
3
    [
4
      {"message":"cannot query field 'thisfielddoesnotexist' on type 'User'",
5
       "extensions":{"type":"User","field":"thisfielddoesnotexist","code":"INVALID_FIELD"}
6
      }
7
    ]
8
  },
9
  {"data":{"me":{"name":"Ada Lovelace"}}}
10
]