Extensions

Request extensions

The GraphQL over HTTP spec defines an optional extensions field on requests. This is sent as a top-level key in the request payload alongside query, variables, and operationName.

You can use this to pass protocol extensions such as trusted documents:

from gql import Client, GraphQLRequest
from gql.transport.aiohttp import AIOHTTPTransport

transport = AIOHTTPTransport(url="https://example.com/graphql")

async with Client(transport=transport) as session:

    request = GraphQLRequest(
        "query { viewer { name } }",
        extensions={
            "document-id": "155d6e8f5545...",
        },
    )

    result = await session.execute(request)

Response extensions

When you execute (or subscribe) GraphQL requests, the server will send responses which may have 3 fields:

• data: the serialized response from the backend

• errors: a list of potential errors

• extensions: an optional field for additional data

If there are errors in the response, then the execute or subscribe methods will raise a TransportQueryError.

If no errors are present, then only the data from the response is returned by default.

result = client.execute(query)
# result is here the content of the data field

If you need to receive the extensions data too, then you can run the execute or subscribe methods with get_execution_result=True.

In that case, the full execution result is returned and you can have access to the extensions field

result = client.execute(query, get_execution_result=True)
# result is here an ExecutionResult instance

# result.data is the content of the data field
# result.extensions is the content of the extensions field