Resolvers

Intro

In Ariadne, a resolver is any Python callable that accepts two positional arguments (obj and info):

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

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

obj is a value returned by an obj resolver. If the resolver is a root resolver (it belongs to the field defined on Query or Mutation) and GraphQL server implementation doesn’t explicitly define value for this field, the value of this argument will be None.

info is the instance of a GraphQLResolveInfo object specific for this field and query. It defines a special context attribute that contains any value that GraphQL server provided for resolvers on the query execution. Its type and contents are application-specific, but it is generally expected to contain application-specific data such as authentication state of the user or http request.

Note

context is just one of many attributes that can be found on GraphQLResolveInfo, but it is by far the most commonly used one. Other attributes enable developers to introspect the query that is currently executed and implement new utilities and abstractions, but documenting that is out of Ariadne’s scope. If you are interested, you can find the list of all attributes here.

Resolver maps

A resolver needs to be bound to a valid type’s field in the schema in order to be used during the query execution.

To bind resolvers to schema, Ariadne uses a special ResolverMap object that is initialized with single argument - name of the type:

from ariadne import ResolverMap

query = ResolverMap("Query")

The above ResolverMap instance knows that it maps its resolvers to Query type, and enables you to assign resolver functions to these type fields. This can be done using the field method implemented by the resolver map:

from ariadne import ResolverMap

type_defs = """
    type Query {
        hello: String!
    }
"""

query = ResolverMap("Query")

@query.field("hello")
def resolve_hello(*_):
    return "Hello!"

@query.field decorator is non-wrapping - it simply registers a given function as a resolver for specified field and then returns it as it is. This makes it easy to test or reuse resolver functions between different types or even APIs:

user = ResolverMap("User")
client = ResolverMap("Client")

@user.field("email")
@client.field("email")
def resolve_email_with_permission_check(obj, info):
    if info.context.user.is_administrator:
        return obj.email
    return None

Alternatively, query.field can also be called as regular method:

from .resolvers import resolve_email_with_permission_check

user = ResolverMap("User")
user.field("email", resolver=resolve_email_with_permission_check)

Handling arguments

If GraphQL field specifies any arguments, those argument values will be passed to the resolver as keyword arguments:

type_def = """
    type Query {
        holidays(year: Int): [String]!
    }
"""

user = ResolverMap("Query")

@query.field("holidays")
def resolve_holidays(*_, year=None):
    if year:
        Calendar.get_holidays_in_year(year)
    return Calendar.get_all_holidays()

If a field argument is marked as required (by following type with !, eg. year: Int!), you can skip the =None in your kwarg:

@query.field("holidays")
def resolve_holidays(*_, year):
    if year:
        Calendar.get_holidays_in_year(year)
    return Calendar.get_all_holidays()

Aliases

You can use ResolverMap.alias to quickly make a field an alias for a differently-named attribute on a resolved object:

type_def = """
    type User {
        fullName: String
    }
"""

user = ResolverMap("User")
user.alias("fullName", "username")

Fallback resolvers

Schema can potentially define numerous types and fields, and defining a resolver or alias for every single one of them can become a large burden.

Ariadne provides two special “fallback resolvers” that scan schema during initialization, and bind default resolvers to fields that don’t have any resolver set:

from ariadne import fallback_resolvers, start_simple_server
from .typedefs import type_defs
from .resolvers import resolvers

start_simple_server(type_defs, resolvers + [fallback_resolvers])

The above example starts a simple GraphQL API using types and resolvers imported from other modules, but it also adds fallback_resolvers to the list of resolvers that should be used in creation of schema.

fallback_resolvers perform any case conversion and simply seek the attribute named in the same way as the field they are bound to using “default resolver” strategy described in the next chapter.

If your schema uses JavaScript convention for naming its fields (as do all schema definitions in this guide) you may want to instead use the snake_case_fallback_resolvers that converts field name to Python’s snake_case before looking it up on the object:

from ariadne import snake_case_fallback_resolvers, start_simple_server
from .typedefs import type_defs
from .resolvers import resolvers

start_simple_server(type_defs, resolvers + [snake_case_fallback_resolvers])

Default resolver

Both ResolverMap.alias and fallback resolvers use an Ariadne-provided default resolver to implement its functionality.

This resolver takes a target attribute name and (depending if obj is dict or not) uses either obj.get(attr_name) or getattr(obj, attr_name, None) to resolve the value that should be returned.

In the below example, both representations of User type are supported by the default resolver:

type_def = """
    type User {
        likes: Int!
        initials(length: Int!): String
    }
"""

class UserObj:
    username = "admin"

    def likes(self):
        return count_user_likes(self)

    def initials(self, length)
        return self.name[:length]

user_dict = {
    "likes": lambda obj, *_: count_user_likes(obj),
    "initials": lambda obj, *_, length: obj.username[:length])
}

Understanding schema binding

When Ariadne initializes GraphQL server, it iterates over a list of objects passed to a resolvers argument and calls bind_to_schema method of each item with a single argument: instance of GraphQLSchema object representing parsed schema used by the server.

ResolverMap and the fallback resolvers introduced above don’t access the schema until their bind_to_schema method is called. It is safe to create, call methods and perform other state mutations on those objects until they are passed to Ariadne.

You can easily implement a custom utility class that can be used in Ariadne:

from graphql.type import GraphQLSchema

class MyResolverMap:
    def bind_to_schema(self, schema: GraphQLSchema) -> None:
        pass  # insert custom logic here

In later parts of the documentation, other special types will be introduced that internally use bind_to_schema to implement their logic.