Addind Batching docs

graphql-python · leszekhanusz · May 27, 2025 · May 26, 2025 · May 27, 2025 · May 27, 2025
commit 93274eadc8f6fe36238cc95628890ef64d5fb782
diff --git a/README.md b/README.md
@@ -40,6 +40,7 @@ The complete documentation for GQL can be found at
 * Supports [sync or async usage](https://gql.readthedocs.io/en/latest/async/index.html), [allowing concurrent requests](https://gql.readthedocs.io/en/latest/advanced/async_advanced_usage.html#async-advanced-usage)
 * Supports [File uploads](https://gql.readthedocs.io/en/latest/usage/file_upload.html)
 * Supports [Custom scalars / Enums](https://gql.readthedocs.io/en/latest/usage/custom_scalars_and_enums.html)
+* Supports [Batching requests](https://gql.readthedocs.io/en/latest/advanced/batching_requests.html)
 * [gql-cli script](https://gql.readthedocs.io/en/latest/gql-cli/intro.html) to execute GraphQL queries or download schemas from the command line
 * [DSL module](https://gql.readthedocs.io/en/latest/advanced/dsl_module.html) to compose GraphQL queries dynamically
 

diff --git a/docs/advanced/batching_requests.rst b/docs/advanced/batching_requests.rst
@@ -0,0 +1,96 @@
+.. _batching_requests:
+
+Batching requests
+=================
+
+If you need to send multiple GraphQL queries to a backend,
+and if the backend supports batch requests,
+then you might want to send those requests in a batch instead of
+making multiple execution requests.
+
+.. warning::
+    - Some backends do not support batch requests
+    - File uploads and subscriptions are not supported with batch requests
+
+Batching requests manually
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To execute a batch of requests manually:
+
+- First Make a list of :class:`GraphQLRequest <gql.GraphQLRequest>` objects, containing:
+   * your GraphQL query
+   * Optional variable_values
+   * Optional operation_name
+
+.. code-block:: python
+
+    request1 = GraphQLRequest("""
+        query getContinents {
+          continents {
+            code
+            name
+          }
+        }
+        """
+    )
+
+    request2 = GraphQLRequest("""
+        query getContinentName ($code: ID!) {
+          continent (code: $code) {
+            name
+          }
+        }
+        """,
+        variable_values={
+          "code": "AF",
+        },
+    )
+
+    requests = [request1, request2]
+
+- Then use one of the `execute_batch` methods, either on Client,
+  or in a sync or async session
+
+**Sync**:
+
+.. code-block:: python
+
+    transport = RequestsHTTPTransport(url=url)
+    # Or transport = HTTPXTransport(url=url)
+
+    with Client(transport=transport) as session:
+
+        results = session.execute_batch(requests)
+
+        result1 = results[0]
+        result2 = results[1]
+
+**Async**:
+
+.. code-block:: python
+
+    transport = AIOHTTPTransport(url=url)
+    # Or transport = HTTPXAsyncTransport(url=url)
+
+    async with Client(transport=transport) as session:
+
+        results = await session.execute_batch(requests)
+
+        result1 = results[0]
+        result2 = results[1]
+
+.. note::
+    If any request in the batch returns an error, then a TransportQueryError will be raised
+    with the first error found.
+
+Automatic Batching of requests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your code execute multiple requests independently in a short time
+(either from different threads in sync code, or from different asyncio tasks in async code),
+then you can use gql automatic batching of request functionality.
+
+You define a :code:`batching_interval` in your :class:`Client <gql.Client>`
+and each time a new execution request is received through an `execute` method,
+we will wait that interval (in seconds) for other requests to arrive
+before sending all the requests received in that interval in a single batch.
diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
@@ -6,6 +6,7 @@ Advanced
 
    async_advanced_usage
    async_permanent_session
+   batching_requests
    logging
    error_handling
    local_schema