Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: query batching data consistency #6903

Open
wants to merge 3 commits into
base: dev
Choose a base branch
from
+17 −7
Open

docs: query batching data consistency #6903

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f66c608
DOC-375 clarify data consistency as primary benefit of query batching
shorgi Mar 3, 2025
8339749
copyedit
shorgi Mar 4, 2025
7b0acc8
Merge branch 'dev' into eh/DOC-375
shorgi Mar 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 17 additions & 7 deletions docs/source/routing/performance/query-batching.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,24 @@
---
title: Query Batching
subtitle: Receive query batches with the GraphOS Router
description: Handle multiple GraphQL requests with GraphOS Router's query batching capabilities. Aggregate operations into single HTTP requests, reducing overhead.
description: Handle multiple GraphQL requests with GraphOS Router's query batching capabilities. Aggregate operations into single HTTP requests, preserving data consistency and reducing performance overhead.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should get rid of "performance overhead". Batching shouldn't be used for perf optimisations, but rather for data consistency. In fact, most of the times batching operations is going to negatively affect performance, but if you're doing this for data consistency purposes, you are usually okay with the performance hit.

---

<EnterpriseFeature />

Learn about query batching and how to configure the GraphOS Router to receive query batches.
Learn how query batching can help preserve data consistency of responses, and learn how to configure the GraphOS Router to receive query batches.

## About query batching
## 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.
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably add an extra line here saying this is not a performance optimisation, but one of the solutions to data consistency.


### Preserving data consistency

When the underlying data is changing rapidly, the separate requests of an application may result in responses with inconsistent data. Given two requests for a single page, the values returned in their responses may be different because the data's been updated or subgraph servers briefly had different values.

To prevent this inconsistency from happening, clients can bundle multiple requests together into a batch so routers or servers can produce responses with consistent data. MFE-based UIs usually batch multiple client operations, issued close together, into a single HTTP request. Both Apollo Client and Apollo Server support this.

### Router batching support

The router's batching support is provided by two sets of functionality:
- client batching
Expand All @@ -22,12 +30,14 @@ With subgraph batching, the router analyzes input client batch requests and issu

The GraphOS Router supports client and subgraph query batching.

The GraphOS 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. 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.

### Client batching support

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 GraphOS 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. 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 client query batching

Both the GraphOS Router and client need to be configured to support query batching.
Expand Down Expand Up @@ -87,7 +97,7 @@ batching:

- There are limitations on the ability of the router to preserve batches from the client request into the subgraph requests. In particular, certain forms of queries will require data to be present before they are processed. Consequently, the router will only be able to generate batches from queries which are processed which don't contain such constraints. This may result in the router issuing multiple batches or requests.

- If [query deduplication](/router/configuration/traffic-shaping/#query-deduplication) or [entity caching](/router/configuration/entity-caching) are enabled, they will not apply to batched queries. Batching will take precedence over query deduplication and entity caching. Query deduplication and Entity caching will still be performed for non-batched queries.
- If [query deduplication](/router/configuration/traffic-shaping/#query-deduplication) or [entity caching](/router/configuration/entity-caching) are enabled, they will not apply to batched queries. Batching will take precedence over query deduplication and entity caching. Query deduplication and entity caching will still be performed for non-batched queries.

</Note>

Expand Down