Reference

GraphQL-core

The primary graphql package includes everything you need to define a GraphQL schema and fulfill GraphQL requests.

GraphQL-core provides a reference implementation for the GraphQL specification but is also a useful utility for operating on GraphQL files and building sophisticated tools.

This top-level package exports a general purpose function for fulfilling all steps of the GraphQL specification in a single operation, but also includes utilities for every part of the GraphQL specification:

  • Parsing the GraphQL language.
  • Building a GraphQL type schema.
  • Validating a GraphQL request against a type schema.
  • Executing a GraphQL request against a type schema.

This also includes utility functions for operating on GraphQL types and GraphQL documents to facilitate building tools.

You may also import from each sub-package directly. For example, the following two import statements are equivalent:

from graphql import parse
from graphql.language import parse

The sub-packages of GraphQL-core 3 are:

Top-Level Functions

graphql.graphql(schema: graphql.type.schema.GraphQLSchema, source: Union[str, graphql.language.source.Source], root_value: Any = None, context_value: Any = None, variable_values: Dict[str, Any] = None, operation_name: str = None, field_resolver: Callable[[...], Any] = None, type_resolver: Callable[[Any, graphql.type.definition.GraphQLResolveInfo, GraphQLAbstractType], Union[Awaitable[Union[GraphQLObjectType, str, None]], GraphQLObjectType, str, None]] = None, middleware: Union[Tuple, List[T], graphql.execution.middleware.MiddlewareManager, None] = None, execution_context_class: Type[graphql.execution.execute.ExecutionContext] = <class 'graphql.execution.execute.ExecutionContext'>) → graphql.execution.execute.ExecutionResult

Execute a GraphQL operation asynchronously.

This is the primary entry point function for fulfilling GraphQL operations by parsing, validating, and executing a GraphQL document along side a GraphQL schema.

More sophisticated GraphQL servers, such as those which persist queries, may wish to separate the validation and execution phases to a static time tooling step, and a server runtime step.

Accepts the following arguments:

Parameters:
  • schema – The GraphQL type system to use when validating and executing a query.
  • source – A GraphQL language formatted string representing the requested operation.
  • root_value – The value provided as the first argument to resolver functions on the top level type (e.g. the query object type).
  • context_value – The context value is provided as an attribute of the second argument (the resolve info) to resolver functions. It is used to pass shared information useful at any point during query execution, for example the currently logged in user and connections to databases or other services.
  • variable_values – A mapping of variable name to runtime value to use for all variables defined in the request string.
  • operation_name – The name of the operation to use if request string contains multiple possible operations. Can be omitted if request string contains only one operation.
  • field_resolver – A resolver function to use when one is not provided by the schema. If not provided, the default field resolver is used (which looks for a value or method on the source value with the field’s name).
  • type_resolver – A type resolver function to use when none is provided by the schema. If not provided, the default type resolver is used (which looks for a __typename field or alternatively calls the is_type_of method).
  • middleware – The middleware to wrap the resolvers with
  • execution_context_class – The execution context class to use to build the context
graphql.graphql_sync(schema: graphql.type.schema.GraphQLSchema, source: Union[str, graphql.language.source.Source], root_value: Any = None, context_value: Any = None, variable_values: Dict[str, Any] = None, operation_name: str = None, field_resolver: Callable[[...], Any] = None, type_resolver: Callable[[Any, graphql.type.definition.GraphQLResolveInfo, GraphQLAbstractType], Union[Awaitable[Union[GraphQLObjectType, str, None]], GraphQLObjectType, str, None]] = None, middleware: Union[Tuple, List[T], graphql.execution.middleware.MiddlewareManager, None] = None, execution_context_class: Type[graphql.execution.execute.ExecutionContext] = <class 'graphql.execution.execute.ExecutionContext'>) → graphql.execution.execute.ExecutionResult

Execute a GraphQL operation synchronously.

The graphql_sync function also fulfills GraphQL operations by parsing, validating, and executing a GraphQL document along side a GraphQL schema. However, it guarantees to complete synchronously (or throw an error) assuming that all field resolvers are also synchronous.