Docs
Launch GraphOS Studio

Query batching

Receive query batches with the Apollo Router


This feature is currently experimental. Your questions and feedback are highly valueddon'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 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 s, issued close together, into a single HTTP request. This is supported in Apollo Client and Apollo Server.

The Apollo 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 s sent to the router.

Once configured, Apollo Client automatically combines multiple s 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 must be configured to receive query batches, otherwise it rejects them. When processing a batch, the router deserializes and processes each 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 and client need to be configured to support query batching.

Configure router

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

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

router.yaml
experimental_batching:
enabled: true
mode: batch_http_link
AttributeDescriptionValid ValuesDefault Value
enabledFlag to enable reception of client query batchesbooleanfalse
modeSupported client batching modebatch_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 receives a query batch from a client, and batching is not enabled, the sends a BATCHING_NOT_ENABLED error to the client.

Metrics for query batching

Metrics in the Apollo for query batching:

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

[
query MyFirstQuery {
me {
id
}
},
query MySecondQuery {
me {
name
}
}
]

Response format

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

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

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:

[
query MyFirstQuery {
me {
id
}
},,
query MySecondQuery {
me {
name
}
}
]

As a result, the returns an invalid batch error:

{"errors":
[
{"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"}}
]
}

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 that doesn't exist, while the rest of the batch query is valid.

[
query MyFirstQuery {
me {
thisfielddoesnotexist
}
},
query MySecondQuery {
me {
name
}
}
]

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

[
{"errors":
[
{"message":"cannot query field 'thisfielddoesnotexist' on type 'User'",
"extensions":{"type":"User","field":"thisfielddoesnotexist","code":"INVALID_FIELD"}
}
]
},
{"data":{"me":{"name":"Ada Lovelace"}}}
]

Known limitations

Unsupported query modes

When batching is enabled, any batch that results in a stream of responses is unsupported, including:

Previous
Request format
Next
Subscriptions setup
Edit on GitHubEditForumsDiscord