Ariadne

In Ariadne, a resolver is any Python callable (synchronous or asynchronous) that accepts two positional arguments:

1. obj: The value returned by the parent resolver. For root resolvers (on Query, Mutation, or Subscription), this is None if the server doesn't explicitly define a value.
2. info: An instance of GraphQLResolveInfo. The most commonly used attribute on this object is info.context, which contains application-specific data like authentication state or HTTP requests.

Resolvers can be standard functions or classes implementing __call__.

def example_resolver(obj: Any, info: GraphQLResolveInfo):
    return obj.do_something()

class FormResolver:
    def __call__(self, obj: Any, info: GraphQLResolveInfo, **data):
        ...

Ariadne's subscription handler system is transport-agnostic, allowing you to implement custom delivery mechanisms such as Server-Sent Events (SSE) for browsers or HTTP callbacks for gateway architectures.

Key benefits include:

• Flexibility: Implement any transport protocol.
• Reusability: Share subscription execution logic via generate_events().
• Composability: Combine multiple handlers for different clients.
• Clean separation: Transport concerns are separated from GraphQL execution logic.

The N+1 problem occurs when a GraphQL query retrieves a list of $N$ items, and for each item, a separate resolver is triggered to fetch a related object. This results in $1$ initial query for the list plus $N$ additional queries for the related data, leading to significant performance degradation.

For example, if you fetch 20 messages and each message has a poster field that triggers a database lookup, you will execute 21 database queries instead of one efficient join or batch request.

Ariadne follows a schema-first approach, meaning you define your API structure using Schema Definition Language (SDL) before implementing logic.

The workflow consists of three main steps:

1. Define Schema: Write your types, queries, and mutations in SDL. Use the gql() function to wrap these strings; this provides syntax validation and better error tracebacks during development.
2. Bind Resolvers:
   • Use QueryType to bind Python functions to top-level fields in the Query type.
   • Use ObjectType to bind Python functions to specific fields of a custom type (e.g., adding a fullName field to a Person type).
3. Execute: Use make_executable_schema() to combine your SDL and your type objects into a single executable schema, which can then be passed to an ASGI or WSGI application.

The Ariadne GraphQL application uses Starlette's Request class. When writing ASGI middleware, do not mutate the request object directly. Instead, store additional data within the request.scope dictionary to ensure compatibility with the ASGI specification.

# This is wrong
request.app_data

# This is correct
request.scope["app_data"]

To access Flask-specific information (like headers or session data) inside an Ariadne resolver, you must pass the Flask request object into the context_value argument of graphql_sync during the POST request handling.

In your resolver function, the request object will then be available via info.context.

# In the Flask route:
success, result = graphql_sync(
    schema,
    data,
    context_value={"request": request},
    debug=app.debug
)

# In the resolver:
@query.field("hello")
def resolve_hello(_, info):
    request = info.context
    user_agent = request.headers.get("User-Agent", "Guest")
    return "Hello, %s!" % user_agent

Deciding whether to use an async def or a standard def for your subscription source depends on your library ecosystem and performance requirements.

Use Async Generators when:

• You have access to async-native libraries (e.g., aiohttp, asyncpg).
• You require maximum concurrency.
• You are already working within an async context.

Use Sync Generators when:

• You must use legacy or synchronous-only libraries.
• Blocking I/O is unavoidable.
• You want to simplify your codebase by avoiding async/await complexity.
• You are migrating existing synchronous code to GraphQL subscriptions.

InterfaceType is a specialized class used to handle GraphQL interfaces. It serves two primary purposes:

1. Type Resolution: It uses a type_resolver function to determine which concrete type an object belongs to at runtime. This resolver receives the object (obj) and the context (*_).
2. Shared Field Resolvers: It allows you to define resolvers for fields that are common to all implementing types.

Key Behavior Note: Unlike ObjectType, an InterfaceType will only assign a resolver to a field if that field does not already have a resolver set on the concrete type. This allows concrete types to override interface-level field resolvers.

To implement GraphQL subscriptions, use the SubscriptionType class. A subscription requires two distinct parts for each field:

1. Subscription Source (Subscriber): A generator function (sync or async) that yields events or messages. This function is responsible for listening to an event stream (e.g., via a message broker) and yielding data when events occur. Sync generators are automatically wrapped to run in worker threads.
2. Subscription Resolver: A function called with the message yielded by the source. Its role is to transform that message into the Python representation of the GraphQL type.

Arguments defined on the GraphQL subscription field are passed to both the source and the resolver functions.

Use the @subscription_type.source("field_name") decorator to bind a source to a field, and @subscription_type.field("field_name") to bind the resolver.