1. Overview

Spring for GraphQL provides support for Spring applications built on GraphQL Java. It is a joint collaboration between the GraphQL Java team and Spring engineering.

Spring for GraphQL is the successor of the GraphQL Java Spring project from the GraphQL Java team. It aims to be the foundation for all Spring, GraphQL applications.

Please, use our issue tracker to report a problem, discuss a design issue, or to request a feature.

Check the Wiki. for what’s new, baseline requirements, and upgrade notes, and other cross-version information.

To get started, see the Boot Starter and Samples sections.

2. Server Transports

Spring for GraphQL supports server handling of GraphQL requests over HTTP, WebSocket, and RSocket.

3. HTTP

GraphQlHttpHandler handles GraphQL over HTTP requests and delegates to the Interception chain for request execution. There are two variants, one for Spring MVC and one for Spring WebFlux. Both handle requests asynchronously and have equivalent functionality, but rely on blocking vs non-blocking I/O respectively for writing the HTTP response.

Requests must use HTTP POST with "application/json" as content type and GraphQL request details included as JSON in the request body, as defined in the proposed GraphQL over HTTP specification. Once the JSON body has been successfully decoded, the HTTP response status is always 200 (OK), and any errors from GraphQL request execution appear in the "errors" section of the GraphQL response. The default and preferred choice of media type is "application/graphql-response+json", but "application/json" is also supported, as described in the specification.

GraphQlHttpHandler can be exposed as an HTTP endpoint by declaring a RouterFunction bean and using the RouterFunctions from Spring MVC or WebFlux to create the route. The Boot Starter does this, see the Web Endpoints section for details, or check GraphQlWebMvcAutoConfiguration or GraphQlWebFluxAutoConfiguration it contains, for the actual config.

The 1.0.x branch of this repository contains a Spring MVC HTTP sample application.

3.1. WebSocket

GraphQlWebSocketHandler handles GraphQL over WebSocket requests based on the protocol defined in the graphql-ws library. The main reason to use GraphQL over WebSocket is subscriptions which allow sending a stream of GraphQL responses, but it can also be used for regular queries with a single response. The handler delegates every request to the Interception chain for further request execution.

GraphQL Over WebSocket Protocols

There are two such protocols, one in the subscriptions-transport-ws library and another in the graphql-ws library. The former is not active and succeeded by the latter. Read this blog post for the history.

There are two variants of GraphQlWebSocketHandler, one for Spring MVC and one for Spring WebFlux. Both handle requests asynchronously and have equivalent functionality. The WebFlux handler also uses non-blocking I/O and back pressure to stream messages, which works well since in GraphQL Java a subscription response is a Reactive Streams Publisher.

The graphql-ws project lists a number of recipes for client use.

GraphQlWebSocketHandler can be exposed as a WebSocket endpoint by declaring a SimpleUrlHandlerMapping bean and using it to map the handler to a URL path. By default, the Boot Starter does not expose a GraphQL over WebSocket endpoint, but it’s easy to enable it by adding a property for the endpoint path. Please, see the Web Endpoints section for details, or check the GraphQlWebMvcAutoConfiguration or the GraphQlWebFluxAutoConfiguration for the actual Boot starter config.

The 1.0.x branch of this repository contains a WebFlux WebSocket sample application.

3.2. RSocket

GraphQlRSocketHandler handles GraphQL over RSocket requests. Queries and mutations are expected and handled as an RSocket request-response interaction while subscriptions are handled as request-stream.

GraphQlRSocketHandler can be used a delegate from an @Controller that is mapped to the route for GraphQL requests. For example:

import java.util.Map;

import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import org.springframework.graphql.server.GraphQlRSocketHandler;
import org.springframework.messaging.handler.annotation.MessageMapping;
import org.springframework.stereotype.Controller;

@Controller
public class GraphQlRSocketController {

    private final GraphQlRSocketHandler handler;

    GraphQlRSocketController(GraphQlRSocketHandler handler) {
        this.handler = handler;
    }

    @MessageMapping("graphql")
    public Mono<Map<String, Object>> handle(Map<String, Object> payload) {
        return this.handler.handle(payload);
    }

    @MessageMapping("graphql")
    public Flux<Map<String, Object>> handleSubscription(Map<String, Object> payload) {
        return this.handler.handleSubscription(payload);
    }
}

3.3. Interception

Server transports allow intercepting requests before and after the GraphQL Java engine is called to process a request.

3.3.1. WebGraphQlInterceptor

HTTP and WebSocket transports invoke a chain of 0 or more WebGraphQlInterceptor, followed by an ExecutionGraphQlService that calls the GraphQL Java engine. WebGraphQlInterceptor allows an application to intercept incoming requests and do one of the following:

  • Check HTTP request details

  • Customize the graphql.ExecutionInput

  • Add HTTP response headers

  • Customize the graphql.ExecutionResult

For example, an interceptor can pass an HTTP request header to a DataFetcher:

import java.util.Collections;

import reactor.core.publisher.Mono;

import org.springframework.graphql.data.method.annotation.ContextValue;
import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.server.WebGraphQlInterceptor;
import org.springframework.graphql.server.WebGraphQlRequest;
import org.springframework.graphql.server.WebGraphQlResponse;
import org.springframework.stereotype.Controller;

class RequestHeaderInterceptor implements WebGraphQlInterceptor { (1)

    @Override
    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) {
        String value = request.getHeaders().getFirst("myHeader");
        request.configureExecutionInput((executionInput, builder) ->
                builder.graphQLContext(Collections.singletonMap("myHeader", value)).build());
        return chain.next(request);
    }
}

@Controller
class MyContextValueController { (2)

    @QueryMapping
    Person person(@ContextValue String myHeader) {
        ...
    }
}
1 Interceptor adds HTTP request header value into GraphQLContext
2 Data controller method accesses the value

Reversely, an interceptor can access values added to the GraphQLContext by a controller:

import graphql.GraphQLContext;
import reactor.core.publisher.Mono;

import org.springframework.graphql.data.method.annotation.QueryMapping;
import org.springframework.graphql.server.WebGraphQlInterceptor;
import org.springframework.graphql.server.WebGraphQlRequest;
import org.springframework.graphql.server.WebGraphQlResponse;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseCookie;
import org.springframework.stereotype.Controller;

// Subsequent access from a WebGraphQlInterceptor

class ResponseHeaderInterceptor implements WebGraphQlInterceptor {

    @Override
    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) { (2)
        return chain.next(request).doOnNext(response -> {
            String value = response.getExecutionInput().getGraphQLContext().get("cookieName");
            ResponseCookie cookie = ResponseCookie.from("cookieName", value).build();
            response.getResponseHeaders().add(HttpHeaders.SET_COOKIE, cookie.toString());
        });
    }
}

@Controller
class MyCookieController {

    @QueryMapping
    Person person(GraphQLContext context) { (1)
        context.put("cookieName", "123");
        ...
    }
}
1 Controller adds value to the GraphQLContext
2 Interceptor uses the value to add an HTTP response header

WebGraphQlHandler can modify the ExecutionResult, for example, to inspect and modify request validation errors that are raised before execution begins and which cannot be handled with a DataFetcherExceptionResolver:

import java.util.List;

import graphql.GraphQLError;
import graphql.GraphqlErrorBuilder;
import reactor.core.publisher.Mono;

import org.springframework.graphql.server.WebGraphQlInterceptor;
import org.springframework.graphql.server.WebGraphQlRequest;
import org.springframework.graphql.server.WebGraphQlResponse;

class RequestErrorInterceptor implements WebGraphQlInterceptor {

    @Override
    public Mono<WebGraphQlResponse> intercept(WebGraphQlRequest request, Chain chain) {
        return chain.next(request).map(response -> {
            if (response.isValid()) {
                return response; (1)
            }

            List<GraphQLError> errors = response.getErrors().stream() (2)
                    .map(error -> {
                        GraphqlErrorBuilder<?> builder = GraphqlErrorBuilder.newError();
                        // ...
                        return builder.build();
                    })
                    .toList();

            return response.transform(builder -> builder.errors(errors).build()); (3)
        });
    }
}
1 Return the same if ExecutionResult has a "data" key with non-null value
2 Check and transform the GraphQL errors
3 Update the ExecutionResult with the modified errors

Use WebGraphQlHandler to configure the WebGraphQlInterceptor chain. This is supported by the Boot Starter, see Web Endpoints.

3.3.2. RSocketQlInterceptor

Similar to WebGraphQlInterceptor, an RSocketQlInterceptor allows intercepting GraphQL over RSocket requests before and after GraphQL Java engine execution. You can use this to customize the graphql.ExecutionInput and the graphql.ExecutionResult.

4. Request Execution

ExecutionGraphQlService is the main Spring abstraction to call GraphQL Java to execute requests. Underlying transports, such as the HTTP, delegate to ExecutionGraphQlService to handle requests.

The main implementation, DefaultExecutionGraphQlService, is configured with a GraphQlSource for access to the graphql.GraphQL instance to invoke.

4.1. GraphQLSource

GraphQlSource is a contract to expose the graphql.GraphQL instance to use that also includes a builder API to build that instance. The default builder is available via GraphQlSource.schemaResourceBuilder().

The Boot Starter creates an instance of this builder and further initializes it to load schema files from a configurable location, to expose properties to apply to GraphQlSource.Builder, to detect RuntimeWiringConfigurer beans, Instrumentation beans for GraphQL metrics, and DataFetcherExceptionResolver and SubscriptionExceptionResolver beans for exception resolution. For further customizations, you can also declare a GraphQlSourceBuilderCustomizer bean, for example:

@Configuration(proxyBeanMethods = false)
class GraphQlConfig {

    @Bean
    public GraphQlSourceBuilderCustomizer sourceBuilderCustomizer() {
        return (builder) ->
                builder.configureGraphQl(graphQlBuilder ->
                        graphQlBuilder.executionIdProvider(new CustomExecutionIdProvider()));
    }
}

4.1.1. Schema Resources

GraphQlSource.Builder can be configured with one or more Resource instances to be parsed and merged together. That means schema files can be loaded from just about any location.

By default, the Boot starter looks for schema files with extensions ".graphqls" or ".gqls" under the location classpath:graphql/**, which is typically src/main/resources/graphql. You can also use a file system location, or any location supported by the Spring Resource hierarchy, including a custom implementation that loads schema files from remote locations, from storage, or from memory.

Use classpath*:graphql/**/ to find schema files across multiple classpath locations, e.g. across multiple modules.

4.1.2. Schema Creation

By default, GraphQlSource.Builder uses the GraphQL Java SchemaGenerator to create the graphql.schema.GraphQLSchema. This works for typical use, but if you need to use a different generator, e.g. for federation, you can register a schemaFactory callback:

GraphQlSource.Builder builder = ...

builder.schemaResources(..)
        .configureRuntimeWiring(..)
        .schemaFactory((typeDefinitionRegistry, runtimeWiring) -> {
            // create GraphQLSchema
        })

The GraphQlSource section explains how to configure that with Spring Boot.

For an example with Apollo Federation, see federation-jvm-spring-example.

4.1.3. RuntimeWiringConfigurer

You can use RuntimeWiringConfigurer to register:

  • Custom scalar types.

  • Directives handling code.

  • Default TypeResolver for interface and union types.

  • DataFetcher for a field although applications will typically use Annotated Controllers, and those are detected and registered as DataFetcher`s by `AnnotatedControllerConfigurer, which is a RuntimeWiringConfigurer. The Boot Starter automatically registers AnnotatedControllerConfigurer.

GraphQL Java, server applications use Jackson only for serialization to and from maps of data. Client input is parsed into a map. Server output is assembled into a map based on the field selection set. This means you can’t rely on Jackson serialization/deserialization annotations. Instead, you can use custom scalar types.

The Boot Starter detects beans of type RuntimeWiringConfigurer and registers them in the GraphQlSource.Builder. That means in most cases, you’ll' have something like the following in your configuration:

@Configuration
public class GraphQlConfig {

    @Bean
    public RuntimeWiringConfigurer runtimeWiringConfigurer(BookRepository repository) {

        GraphQLScalarType scalarType = ... ;
        SchemaDirectiveWiring directiveWiring = ... ;
        DataFetcher dataFetcher = QuerydslDataFetcher.builder(repository).single();

        return wiringBuilder -> wiringBuilder
                .scalar(scalarType)
                .directiveWiring(directiveWiring)
                .type("Query", builder -> builder.dataFetcher("book", dataFetcher));
    }
}

If you need to add a WiringFactory, e.g. to make registrations that take into account schema definitions, implement the alternative configure method that accepts both the RuntimeWiring.Builder and an output List<WiringFactory>. This allows you to add any number of factories that are then invoked in sequence.

4.1.4. TypeResolver

GraphQlSource.Builder registers ClassNameTypeResolver as the default TypeResolver to use for GraphQL Interfaces and Unions that don’t already have such a registration through a RuntimeWiringConfigurer. The purpose of a TypeResolver in GraphQL Java is to determine the GraphQL Object type for values returned from the DataFetcher for a GraphQL Interface or Union field.

ClassNameTypeResolver tries to match the simple class name of the value to a GraphQL Object Type and if it is not successful, it also navigates its super types including base classes and interfaces, looking for a match. ClassNameTypeResolver provides an option to configure a name extracting function along with Class to GraphQL Object type name mappings that should help to cover more corner cases:

GraphQlSource.Builder builder = ...
ClassNameTypeResolver classNameTypeResolver = new ClassNameTypeResolver();
classNameTypeResolver.setClassNameExtractor((klass) -> {
    // Implement Custom ClassName Extractor here
});
builder.defaultTypeResolver(classNameTypeResolver);

The GraphQlSource section explains how to configure that with Spring Boot.

4.1.5. Directives

The GraphQL language supports directives that "describe alternate runtime execution and type validation behavior in a GraphQL document". Directives are similar to annotations in Java but declared on types, fields, fragments and operations in a GraphQL document.

GraphQL Java provides the SchemaDirectiveWiring contract to help applications detect and handle directives. For more details, see Schema Directives in the GraphQL Java documentation.

In Spring GraphQL you can register a SchemaDirectiveWiring through a RuntimeWiringConfigurer. The Boot Starter detects such beans, so you might have something like:

@Configuration
public class GraphQlConfig {

     @Bean
     public RuntimeWiringConfigurer runtimeWiringConfigurer() {
          return builder -> builder.directiveWiring(new MySchemaDirectiveWiring());
     }

}
For an example of directives support check out the Extended Validation for Graphql Java library.

4.1.6. Schema Transformation

You can register a graphql.schema.GraphQLTypeVisitor via builder.schemaResources(..).typeVisitorsToTransformSchema(..) if you want to traverse and transform the schema after it is created, and make changes to the schema. Keep in mind that this is more expensive than Schema Traversal so generally prefer traversal to transformation unless you need to make schema changes.

4.1.7. Schema Traversal

You can register a graphql.schema.GraphQLTypeVisitor via builder.schemaResources(..).typeVisitors(..) if you want to traverse the schema after it is created, and possibly apply changes to the GraphQLCodeRegistry. Keep in mind, however, that such a visitor cannot change the schema. See Schema Transformation, if you need to make changes to the schema.

4.1.8. Schema Mapping Inspection

If a query, mutation, or subscription operation does not have a DataFetcher, it won’t return any data, and won’t do anything useful. Likewise, fields on schema types returned by an operation that are covered neither explicitly through a DataFetcher registration, nor implicitly by the default PropertyDataFetcher, which looks for a matching Java object property, will always be null.

GraphQL Java does not perform checks to ensure every schema field is covered, and that can result in gaps that might not be discovered depending on test coverage. At runtime you may get a "silent" null, or an error if the field is not nullable. As a lower level library, GraphQL Java simply does not know enough about DataFetcher implementations and their return types, and therefore can’t compare schema type structure against Java object structure.

Spring for GraphQL defines the SelfDescribingDataFetcher interface to allow a DataFetcher to expose return type information. All Spring DataFetcher implementations implement this interface. That includes those for Annotated Controllers, and those for Querydsl and Query by Example Spring Data repositories. For annotated controllers, the return type is derived from the declared return type on a @SchemaMapping method.

On startup, Spring for GraphQL can inspect schema fields, DataFetcher registrations, and the properties of Java objects returned from DataFetcher implementations to check if all schema fields are covered either by an explicitly registered DataFetcher, or a matching Java object property. The inspection also performs a reverse check looking for DataFetcher registrations against schema fields that don’t exist.

To enable inspection of schema mappings:

GraphQlSource.Builder builder = ...

builder.schemaResources(..)
        .inspectSchemaMappings(report -> {
            logger.debug(report);
        })

Below is an example report:

GraphQL schema inspection:
    Unmapped fields: {Book=[title], Author[firstName, lastName]} (1)
    Unmapped registrations: {Book.reviews=BookController#reviews[1 args]} (2)
    Skipped types: [BookOrAuthor] (3)
1 List of schema fields and their source types that are not mapped
2 List of DataFetcher registrations on fields that don’t exist
3 List of schema types that are skipped, as explained next

There are limits to what schema field inspection can do, in particular when there is insufficient Java type information. This is the case if an annotated controller method is declared to return java.lang.Object, or if the return type has an unspecified generic parameter such as List<?>, or if the DataFetcher does not implement SelfDescribingDataFetcher and the return type is not even known. In such cases, the Java object type structure remains unknown, and the schema type is listed as skipped in the resulting report. For every skipped type, a DEBUG message is logged to indicate why it was skipped.

Schema union types are always skipped because there is no way for a controller method to declare such a return type in Java, and the Java type structure is unknown.

Schema interface types are supported only as far as fields declared directly, which are compared against properties on the Java type declared by a SelfDescribingDataFetcher. Additional fields on concrete implementations are not inspected. This could be improved in a future release to also inspect schema interface implementation types and to try to find a match among subtypes of the declared Java return type.

4.1.9. Operation Caching

GraphQL Java must parse and validate an operation before executing it. This may impact performance significantly. To avoid the need to re-parse and validate, an application may configure a PreparsedDocumentProvider that caches and reuses Document instances. The GraphQL Java docs provide more details on query caching through a PreparsedDocumentProvider.

In Spring GraphQL you can register a PreparsedDocumentProvider through GraphQlSource.Builder#configureGraphQl: .

// Typically, accessed through Spring Boot's GraphQlSourceBuilderCustomizer
GraphQlSource.Builder builder = ...

// Create provider
PreparsedDocumentProvider provider = ...

builder.schemaResources(..)
        .configureRuntimeWiring(..)
        .configureGraphQl(graphQLBuilder -> graphQLBuilder.preparsedDocumentProvider(provider))

The GraphQlSource section explains how to configure that with Spring Boot.

4.2. Reactive DataFetcher

The default GraphQlSource builder enables support for a DataFetcher to return Mono or Flux which adapts those to a CompletableFuture where Flux values are aggregated and turned into a List, unless the request is a GraphQL subscription request, in which case the return value remains a Reactive Streams Publisher for streaming GraphQL responses.

A reactive DataFetcher can rely on access to Reactor context propagated from the transport layer, such as from a WebFlux request handling, see WebFlux Context.

4.3. Context Propagation

Spring for GraphQL provides support to transparently propagate context from the HTTP, through GraphQL Java, and to DataFetcher and other components it invokes. This includes both ThreadLocal context from the Spring MVC request handling thread and Reactor Context from the WebFlux processing pipeline.

4.3.1. WebMvc

A DataFetcher and other components invoked by GraphQL Java may not always execute on the same thread as the Spring MVC handler, for example if an asynchronous WebGraphQlInterceptor or DataFetcher switches to a different thread.

Spring for GraphQL supports propagating ThreadLocal values from the Servlet container thread to the thread a DataFetcher and other components invoked by GraphQL Java to execute on. To do this, an application needs to implement io.micrometer.context.ThreadLocalAccessor for a ThreadLocal values of interest:

public class RequestAttributesAccessor implements ThreadLocalAccessor<RequestAttributes> {

    @Override
    public Object key() {
        return RequestAttributesAccessor.class.getName();
    }

    @Override
    public RequestAttributes getValue() {
        return RequestContextHolder.getRequestAttributes();
    }

    @Override
    public void setValue(RequestAttributes attributes) {
        RequestContextHolder.setRequestAttributes(attributes);
    }

    @Override
    public void reset() {
        RequestContextHolder.resetRequestAttributes();
    }

}

You can register a ThreadLocalAccessor manually on startup with the global ContextRegistry instance, which is accessible via io.micrometer.context.ContextRegistry#getInstance(). You can also register it automatically through the java.util.ServiceLoader mechanism.

4.3.2. WebFlux

A Reactive DataFetcher can rely on access to Reactor context that originates from the WebFlux request handling chain. This includes Reactor context added by WebGraphQlInterceptor components.

4.4. Exceptions

In GraphQL Java, DataFetcherExceptionHandler decides how to represent exceptions from data fetching in the "errors" section of the response. An application can register a single handler only.

Spring for GraphQL registers a DataFetcherExceptionHandler that provides default handling and enables the DataFetcherExceptionResolver contract. An application can register any number of resolvers via GraphQLSource builder and those are in order until one them resolves the Exception to a List<graphql.GraphQLError>. The Spring Boot starter detects beans of this type.

DataFetcherExceptionResolverAdapter is a convenient base class with protected methods resolveToSingleError and resolveToMultipleErrors.

The Annotated Controllers programming model enables handling data fetching exceptions with annotated exception handler methods with a flexible method signature, see @GraphQlExceptionHandler for details.

A GraphQLError can be assigned to a category based on the GraphQL Java graphql.ErrorClassification, or the Spring GraphQL ErrorType, which defines the following:

  • BAD_REQUEST

  • UNAUTHORIZED

  • FORBIDDEN

  • NOT_FOUND

  • INTERNAL_ERROR

If an exception remains unresolved, by default it is categorized as an INTERNAL_ERROR with a generic message that includes the category name and the executionId from DataFetchingEnvironment. The message is intentionally opaque to avoid leaking implementation details. Applications can use a DataFetcherExceptionResolver to customize error details.

Unresolved exception are logged at ERROR level along with the executionId to correlate to the error sent to the client. Resolved exceptions are logged at DEBUG level.

4.4.1. Request Exceptions

The GraphQL Java engine may run into validation or other errors when parsing the request and that in turn prevent request execution. In such cases, the response contains a "data" key with null and one or more request-level "errors" that are global, i.e. not having a field path.

DataFetcherExceptionResolver cannot handle such global errors because they are raised before execution begins and before any DataFetcher is invoked. An application can use transport level interceptors to inspect and transform errors in the ExecutionResult. See examples under WebGraphQlInterceptor.

4.4.2. Subscription Exceptions

The Publisher for a subscription request may complete with an error signal in which case the underlying transport (e.g. WebSocket) sends a final "error" type message with a list of GraphQL errors.

DataFetcherExceptionResolver cannot resolve errors from a subscription Publisher, since the data DataFetcher only creates the Publisher initially. After that, the transport subscribes to the Publisher that may then complete with an error.

An application can register a SubscriptionExceptionResolver in order to resolve exceptions from a subscription Publisher in order to resolve those to GraphQL errors to send to the client.

4.5. Pagination

The GraphQL Cursor Connection specification defines a way to navigate large result sets by returning a subset of items at a time where each item is paired with a cursor that clients can use to request more items before or after the referenced item.

The specification calls the pattern "Connections". A schema type with a name that ends on Connection is a Connection Type that represents a paginated result set. All ~Connection types contain an "edges" field where ~Edge type pairs the actual item with a cursor, as well as a "pageInfo" field with boolean flags to indicate if there are more items forward and backward.

4.5.1. Connection Types

Connection type definitions must be created for every type that needs pagination, adding boilerplate and noise to the schema. Spring for GraphQL provides ConnectionTypeDefinitionConfigurer to add these types on startup, if not already present in the parsed schema files. That means in the schema you only need this:

Query {
    books(first:Int, after:String, last:Int, before:String): BookConnection
}

type Book {
    id: ID!
    title: String!
}

Note the spec-defined forward pagination arguments first and after that clients can use to request the first N items after the given cursor, while last and before are backward pagination arguments to request the last N items before the given cursor.

Next, configure ConnectionTypeDefinitionConfigurer as follows:

GraphQlSource.schemaResourceBuilder()
        .schemaResources(..)
        .typeDefinitionConfigurer(new ConnectionTypeDefinitionConfigurer)

and the following type definitions will be transparently added to the schema:

type BookConnection {
    edges: [BookEdge]!
    pageInfo: PageInfo!
}

type BookEdge {
    node: Book!
    cursor: String!
}

type PageInfo {
    hasPreviousPage: Boolean!
    hasNextPage: Boolean!
    startCursor: String
    endCursor: String
}

The Boot Starter registers ConnectionTypeDefinitionConfigurer by default.

4.5.2. ConnectionAdapter

Once Connection Types are available in the schema, you also need equivalent Java types. GraphQL Java provides those, including generic Connection and Edge, as well as a PageInfo.

One option is to populate a Connection and return it from your controller method or DataFetcher. However, this requires boilerplate code to create the Connection, creating cursors, wrapping each item as an Edge, and creating the PageInfo. Moreover, you may already have an underlying pagination mechanism such as when using Spring Data repositories.

Spring for GraphQL defines the ConnectionAdapter contract to adapt a container of items to Connection. Adapters are applied through a DataFetcher decorator that is in turn installed through a ConnectionFieldTypeVisitor. You can configure it as follows:

ConnectionAdapter adapter = ... ;
GraphQLTypeVisitor visitor = ConnectionFieldTypeVisitor.create(List.of(adapter)) (1)

GraphQlSource.schemaResourceBuilder()
        .schemaResources(..)
        .typeDefinitionConfigurer(..)
        .typeVisitors(List.of(visitor)) (2)
1 Create type visitor with one or more ConnectionAdapters.
2 Resister the type visitor.

There are built-in ConnectionAdapters for Spring Data’s Window and Slice. You can also create your own custom adapter. ConnectionAdapter implementations rely on a CursorStrategy to create cursors for returned items. The same strategy is also used to support the Subrange controller method argument that contains pagination input.

4.5.3. CursorStrategy

CursorStrategy is a contract to encode and decode a String cursor that refers to the position of an item within a large result set. The cursor can be based on an index or on a keyset.

A ConnectionAdapter uses this to encode cursors for returned items. Annotated Controllers methods, Querydsl repositories, and Query by Example repositories use it to decode cursors from pagination requests, and create a Subrange.

CursorEncoder is a related contract that further encodes and decodes String cursors to make them opaque to clients. EncodingCursorStrategy combines CursorStrategy with a CursorEncoder. You can use Base64CursorEncoder, NoOpEncoder or create your own.

There is a built-in CursorStrategy for the Spring Data ScrollPosition. The Boot Starter registers a CursorStrategy<ScrollPosition> with Base64Encoder when Spring Data is present.

4.5.4. Sort

There is no standard way to provide sort information in a GraphQL request. However, pagination depends on a stable sort order. You can use a default order, or otherwise expose input types and extract sort details from GraphQL arguments.

There is built-in support for Spring Data’s Sort as a controller method argument. For this to work, you need to have a SortStrategy bean.

4.6. Batch Loading

Given a Book and its Author, we can create one DataFetcher for a book and another for its author. This allows selecting books with or without authors, but it means books and authors aren’t loaded together, which is especially inefficient when querying multiple books as the author for each book is loaded individually. This is known as the N+1 select problem.

4.6.1. DataLoader

GraphQL Java provides a DataLoader mechanism for batch loading of related entities. You can find the full details in the GraphQL Java docs. Below is a summary of how it works:

  1. Register DataLoader's in the DataLoaderRegistry that can load entities, given unique keys.

  2. DataFetcher's can access DataLoader's and use them to load entities by id.

  3. A DataLoader defers loading by returning a future so it can be done in a batch.

  4. DataLoader's maintain a per request cache of loaded entities that can further improve efficiency.

4.6.2. BatchLoaderRegistry

The complete batching loading mechanism in GraphQL Java requires implementing one of several BatchLoader interface, then wrapping and registering those as DataLoaders with a name in the DataLoaderRegistry.

The API in Spring GraphQL is slightly different. For registration, there is only one, central BatchLoaderRegistry exposing factory methods and a builder to create and register any number of batch loading functions:

@Configuration
public class MyConfig {

    public MyConfig(BatchLoaderRegistry registry) {

        registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
                // return Mono<Map<Long, Author>
        });

        // more registrations ...
    }

}

The Boot Starter declares a BatchLoaderRegistry bean that you can inject into your configuration, as shown above, or into any component such as a controller in order register batch loading functions. In turn the BatchLoaderRegistry is injected into DefaultExecutionGraphQlService where it ensures DataLoader registrations per request.

By default, the DataLoader name is based on the class name of the target entity. This allows an @SchemaMapping method to declare a DataLoader argument with a generic type, and without the need for specifying a name. The name, however, can be customized through the BatchLoaderRegistry builder, if necessary, along with other DataLoaderOptions.

To configure default DataLoaderOptions globally, to use as a starting point for any registration, you can override Boot’s BatchLoaderRegistry bean and use the constructor for DefaultBatchLoaderRegistry that accepts Supplier<DataLoaderOptions>.

For many cases, when loading related entities, you can use @BatchMapping controller methods, which are a shortcut for and replace the need to use BatchLoaderRegistry and DataLoader directly.

BatchLoaderRegistry provides other important benefits too. It supports access to the same GraphQLContext from batch loading functions and from @BatchMapping methods, as well as ensures Context Propagation to them. This is why applications are expected to use it. It is possible to perform your own DataLoader registrations directly but such registrations would forgo the above benefits.

4.6.3. Testing Batch Loading

Start by having BatchLoaderRegistry perform registrations on a DataLoaderRegistry:

BatchLoaderRegistry batchLoaderRegistry = new DefaultBatchLoaderRegistry();
// perform registrations...

DataLoaderRegistry dataLoaderRegistry = DataLoaderRegistry.newRegistry().build();
batchLoaderRegistry.registerDataLoaders(dataLoaderRegistry, graphQLContext);

Now you can access and test individual DataLoader's as follows:

DataLoader<Long, Book> loader = dataLoaderRegistry.getDataLoader(Book.class.getName());
loader.load(1L);
loader.loadMany(Arrays.asList(2L, 3L));
List<Book> books = loader.dispatchAndJoin(); // actual loading

assertThat(books).hasSize(3);
assertThat(books.get(0).getName()).isEqualTo("...");
// ...

5. Data Integration

Spring for GraphQL lets you leverage existing Spring technology, following common programming models to expose underlying data sources through GraphQL.

This section discusses an integration layer for Spring Data that provides an easy way to adapt a Querydsl or a Query by Example repository to a DataFetcher, including the option for automated detection and GraphQL Query registration for repositories marked with @GraphQlRepository.

5.1. Querydsl

Spring for GraphQL supports use of Querydsl to fetch data through the Spring Data Querydsl extension. Querydsl provides a flexible yet typesafe approach to express query predicates by generating a meta-model using annotation processors.

For example, declare a repository as QuerydslPredicateExecutor:

public interface AccountRepository extends Repository<Account, Long>,
            QuerydslPredicateExecutor<Account> {
}

Then use it to create a DataFetcher:

// For single result queries
DataFetcher<Account> dataFetcher =
        QuerydslDataFetcher.builder(repository).single();

// For multi-result queries
DataFetcher<Iterable<Account>> dataFetcher =
        QuerydslDataFetcher.builder(repository).many();

// For paginated queries
DataFetcher<Iterable<Account>> dataFetcher =
        QuerydslDataFetcher.builder(repository).scrollable();

You can now register the above DataFetcher through a RuntimeWiringConfigurer.

The DataFetcher builds a Querydsl Predicate from GraphQL arguments, and uses it to fetch data. Spring Data supports QuerydslPredicateExecutor for JPA, MongoDB, and LDAP.

For a single argument that is a GraphQL input type, QuerydslDataFetcher nests one level down, and uses the values from the argument sub-map.

If the repository is ReactiveQuerydslPredicateExecutor, the builder returns DataFetcher<Mono<Account>> or DataFetcher<Flux<Account>>. Spring Data supports this variant for MongoDB.

5.1.1. Build Setup

To configure Querydsl in your build, follow the official reference documentation:

For example:

Gradle
dependencies {
    //...

    annotationProcessor "com.querydsl:querydsl-apt:$querydslVersion:jpa",
            'org.hibernate.javax.persistence:hibernate-jpa-2.1-api:1.0.2.Final',
            'javax.annotation:javax.annotation-api:1.3.2'
}

compileJava {
     options.annotationProcessorPath = configurations.annotationProcessor
}
Maven
<dependencies>
    <!-- ... -->
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <version>${querydsl.version}</version>
        <classifier>jpa</classifier>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.hibernate.javax.persistence</groupId>
        <artifactId>hibernate-jpa-2.1-api</artifactId>
        <version>1.0.2.Final</version>
    </dependency>
    <dependency>
        <groupId>javax.annotation</groupId>
        <artifactId>javax.annotation-api</artifactId>
        <version>1.3.2</version>
    </dependency>
</dependencies>
<plugins>
    <!-- Annotation processor configuration -->
    <plugin>
        <groupId>com.mysema.maven</groupId>
        <artifactId>apt-maven-plugin</artifactId>
        <version>${apt-maven-plugin.version}</version>
        <executions>
            <execution>
                <goals>
                    <goal>process</goal>
                </goals>
                <configuration>
                    <outputDirectory>target/generated-sources/java</outputDirectory>
                    <processor>com.querydsl.apt.jpa.JPAAnnotationProcessor</processor>
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>

The webmvc-http sample uses Querydsl for artifactRepositories.

5.1.2. Customizations

QuerydslDataFetcher supports customizing how GraphQL arguments are bound onto properties to create a Querydsl Predicate. By default, arguments are bound as "is equal to" for each available property. To customize that, you can use QuerydslDataFetcher builder methods to provide a QuerydslBinderCustomizer.

A repository may itself be an instance of QuerydslBinderCustomizer. This is auto-detected and transparently applied during Auto-Registration. However, when manually building a QuerydslDataFetcher you will need to use builder methods to apply it.

QuerydslDataFetcher supports interface and DTO projections to transform query results before returning these for further GraphQL processing.

To learn what projections are, please refer to the Spring Data docs. To understand how to use projections in GraphQL, please see Selection Set vs Projections.

To use Spring Data projections with Querydsl repositories, create either a projection interface or a target DTO class and configure it through the projectAs method to obtain a DataFetcher producing the target type:

class Account {

    String name, identifier, description;

    Person owner;
}

interface AccountProjection {

    String getName();

    String getIdentifier();
}

// For single result queries
DataFetcher<AccountProjection> dataFetcher =
        QuerydslDataFetcher.builder(repository).projectAs(AccountProjection.class).single();

// For multi-result queries
DataFetcher<Iterable<AccountProjection>> dataFetcher =
        QuerydslDataFetcher.builder(repository).projectAs(AccountProjection.class).many();

5.1.3. Auto-Registration

If a repository is annotated with @GraphQlRepository, it is automatically registered for queries that do not already have a registered DataFetcher and whose return type matches that of the repository domain type. This includes single value queries, multi-value queries, and paginated queries.

By default, the name of the GraphQL type returned by the query must match the simple name of the repository domain type. If needed, you can use the typeName attribute of @GraphQlRepository to specify the target GraphQL type name.

For paginated queries, the simple name of the repository domain type must match the Connection type name without the Connection ending (e.g. Book matches BooksConnection). For auto-registration, pagination is offset-based with 20 items per page.

Auto-registration detects if a given repository implements QuerydslBinderCustomizer and transparently applies that through QuerydslDataFetcher builder methods.

Auto-registration is performed through a built-in RuntimeWiringConfigurer that can be obtained from QuerydslDataFetcher. The Boot Starter automatically detects @GraphQlRepository beans and uses them to initialize the RuntimeWiringConfigurer with.

Auto-registration applies customizations by calling customize(Builder) on the repository instance if your repository implements QuerydslBuilderCustomizer or ReactiveQuerydslBuilderCustomizer respectively.

5.2. Query by Example

Spring Data supports the use of Query by Example to fetch data. Query by Example (QBE) is a simple querying technique that does not require you to write queries through store-specific query languages.

Start by declaring a repository that is QueryByExampleExecutor:

public interface AccountRepository extends Repository<Account, Long>,
            QueryByExampleExecutor<Account> {
}

Use QueryByExampleDataFetcher to turn the repository into a DataFetcher:

// For single result queries
DataFetcher<Account> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).single();

// For multi-result queries
DataFetcher<Iterable<Account>> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).many();

// For paginated queries
DataFetcher<Iterable<Account>> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).scrollable();

You can now register the above DataFetcher through a RuntimeWiringConfigurer.

The DataFetcher uses the GraphQL arguments map to create the domain type of the repository and use that as the example object to fetch data with. Spring Data supports QueryByExampleDataFetcher for JPA, MongoDB, Neo4j, and Redis.

For a single argument that is a GraphQL input type, QueryByExampleDataFetcher nests one level down, and binds with the values from the argument sub-map.

If the repository is ReactiveQueryByExampleExecutor, the builder returns DataFetcher<Mono<Account>> or DataFetcher<Flux<Account>>. Spring Data supports this variant for MongoDB, Neo4j, Redis, and R2dbc.

5.2.1. Build Setup

Query by Example is already included in the Spring Data modules for the data stores where it is supported, so no extra setup is required to enable it.

5.2.2. Customizations

QueryByExampleDataFetcher supports interface and DTO projections to transform query results before returning these for further GraphQL processing.

To learn what projections are, please refer to the Spring Data documentation. To understand the role of projections in GraphQL, please see Selection Set vs Projections.

To use Spring Data projections with Query by Example repositories, create either a projection interface or a target DTO class and configure it through the projectAs method to obtain a DataFetcher producing the target type:

class Account {

    String name, identifier, description;

    Person owner;
}

interface AccountProjection {

    String getName();

    String getIdentifier();
}

// For single result queries
DataFetcher<AccountProjection> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).projectAs(AccountProjection.class).single();

// For multi-result queries
DataFetcher<Iterable<AccountProjection>> dataFetcher =
        QueryByExampleDataFetcher.builder(repository).projectAs(AccountProjection.class).many();

5.2.3. Auto-Registration

If a repository is annotated with @GraphQlRepository, it is automatically registered for queries that do not already have a registered DataFetcher and whose return type matches that of the repository domain type. This includes single value queries, multi-value queries, and paginated queries.

By default, the name of the GraphQL type returned by the query must match the simple name of the repository domain type. If needed, you can use the typeName attribute of @GraphQlRepository to specify the target GraphQL type name.

For paginated queries, the simple name of the repository domain type must match the Connection type name without the Connection ending (e.g. Book matches BooksConnection). For auto-registration, pagination is offset-based with 20 items per page.

Auto-registration is performed through a built-in RuntimeWiringConfigurer that can be obtained from QueryByExampleDataFetcher. The Boot Starter automatically detects @GraphQlRepository beans and uses them to initialize the RuntimeWiringConfigurer with.

Auto-registration applies customizations by calling customize(Builder) on the repository instance if your repository implements QueryByExampleBuilderCustomizer or ReactiveQueryByExampleBuilderCustomizer respectively.

5.3. Selection Set vs Projections

A common question that arises is, how GraphQL selection sets compare to Spring Data projections and what role does each play?

The short answer is that Spring for GraphQL is not a data gateway that translates GraphQL queries directly into SQL or JSON queries. Instead, it lets you leverage existing Spring technology and does not assume a one for one mapping between the GraphQL schema and the underlying data model. That is why client-driven selection and server-side transformation of the data model can play complementary roles.

To better understand, consider that Spring Data promotes domain-driven (DDD) design as the recommended approach to manage complexity in the data layer. In DDD, it is important to adhere to the constraints of an aggregate. By definition an aggregate is valid only if loaded in its entirety, since a partially loaded aggregate may impose limitations on aggregate functionality.

In Spring Data you can choose whether you want your aggregate be exposed as is, or whether to apply transformations to the data model before returning it as a GraphQL result. Sometimes it’s enough to do the former, and by default the Querydsl and the Query by Example integrations turn the GraphQL selection set into property path hints that the underlying Spring Data module uses to limit the selection.

In other cases, it’s useful to reduce or even transform the underlying data model in order to adapt to the GraphQL schema. Spring Data supports this through Interface and DTO Projections.

Interface projections define a fixed set of properties to expose where properties may or may not be null, depending on the data store query result. There are two kinds of interface projections both of which determine what properties to load from the underlying data source:

  • Closed interface projections are helpful if you cannot partially materialize the aggregate object, but you still want to expose a subset of properties.

  • Open interface projections leverage Spring’s @Value annotation and SpEL expressions to apply lightweight data transformations, such as concatenations, computations, or applying static functions to a property.

DTO projections offer a higher level of customization as you can place transformation code either in the constructor or in getter methods.

DTO projections materialize from a query where the individual properties are determined by the projection itself. DTO projections are commonly used with full-args constructors (e.g. Java records), and therefore they can only be constructed if all required fields (or columns) are part of the database query result.

5.4. Scroll

As explained in Pagination, the GraphQL Cursor Connection spec defines a mechanism for pagination with Connection, Edge, and PageInfo schema types, while GraphQL Java provides the equivalent Java type representations.

Spring for GraphQL provides built-in ConnectionAdapter implementations to adapt the Spring Data pagination types Window and Slice transparently. You can configure that as follows:

CursorStrategy<ScrollPosition> strategy = CursorStrategy.withEncoder(
        new ScrollPositionCursorStrategy(),
        CursorEncoder.base64()); (1)

GraphQLTypeVisitor visitor = ConnectionFieldTypeVisitor.create(List.of(
        new WindowConnectionAdapter(strategy),
        new SliceConnectionAdapter(strategy))); (2)

GraphQlSource.schemaResourceBuilder()
        .schemaResources(..)
        .typeDefinitionConfigurer(..)
        .typeVisitors(List.of(visitor)); (3)
1 Create strategy to convert ScrollPosition to a Base64 encoded cursor.
2 Create type visitor to adapt Window and Slice returned from DataFetchers.
3 Register the type visitor.

On the request side, a controller method can declare a ScrollSubrange method argument to paginate forward or backward. For this to work, you must declare a CursorStrategy supports ScrollPosition as a bean.

The Boot Starter declares a CursorStrategy<ScrollPosition> bean, and registers the ConnectionFieldTypeVisitor as shown above if Spring Data is on the classpath.

5.5. Keyset Position

For KeysetScrollPosition, the cursor needs to be created from a keyset, which is essentially a Map of key-value pairs. To decide how to create a cursor from a keyset, you can configure ScrollPositionCursorStrategy with CursorStrategy<Map<String, Object>>. By default, JsonKeysetCursorStrategy writes the keyset Map to JSON. That works for simple like String, Boolean, Integer, and Double, but others cannot be restored back to the same type without target type information. The Jackson library has a default typing feature that can include type information in the JSON. To use it safely you must specify a list of allowed types. For example:

PolymorphicTypeValidator validator = BasicPolymorphicTypeValidator.builder()
        .allowIfBaseType(Map.class)
        .allowIfSubType(ZonedDateTime.class)
        .build();

ObjectMapper mapper = new ObjectMapper();
mapper.activateDefaultTyping(validator, ObjectMapper.DefaultTyping.NON_FINAL);

You can then create JsonKeysetCursorStrategy:

ObjectMapper mapper = ... ;

CodecConfigurer configurer = ServerCodecConfigurer.create();
configurer.defaultCodecs().jackson2JsonDecoder(new Jackson2JsonDecoder(mapper));
configurer.defaultCodecs().jackson2JsonEncoder(new Jackson2JsonEncoder(mapper));

JsonKeysetCursorStrategy strategy = new JsonKeysetCursorStrategy(configurer);

By default, if JsonKeysetCursorStrategy is created without a CodecConfigurer and the Jackson library is on the classpath, customizations like the above are applied for Date, Calendar, and any type from java.time.

5.6. Sort

Spring for GraphQL defines a SortStrategy to create Sort from GraphQL arguments. AbstractSortStrategy implements the contract with abstract methods to extract the sort direction and properties. To enable support for Sort as a controller method argument, you need to declare a SortStrategy bean.

6. Annotated Controllers

Spring for GraphQL provides an annotation-based programming model where @Controller components use annotations to declare handler methods with flexible method signatures to fetch the data for specific GraphQL fields. For example:

@Controller
public class GreetingController {

        @QueryMapping (1)
        public String hello() { (2)
            return "Hello, world!";
        }

}
1 Bind this method to a query, i.e. a field under the Query type.
2 Determine the query from the method name if not declared on the annotation.

Spring for GraphQL uses RuntimeWiring.Builder to register the above handler method as a graphql.schema.DataFetcher for the query named "hello".

6.1. Declaration

You can define @Controller beans as standard Spring bean definitions. The @Controller stereotype allows for auto-detection, aligned with Spring general support for detecting @Controller and @Component classes on the classpath and auto-registering bean definitions for them. It also acts as a stereotype for the annotated class, indicating its role as a data fetching component in a GraphQL application.

AnnotatedControllerConfigurer detects @Controller beans and registers their annotated handler methods as DataFetchers via RuntimeWiring.Builder. It is an implementation of RuntimeWiringConfigurer which can be added to GraphQlSource.Builder. The Boot Starter automatically declares AnnotatedControllerConfigurer as a bean and adds all RuntimeWiringConfigurer beans to GraphQlSource.Builder and that enables support for annotated DataFetchers, see the GraphQL RuntimeWiring section in the Boot starter documentation.

6.2. @SchemaMapping

The @SchemaMapping annotation maps a handler method to a field in the GraphQL schema and declares it to be the DataFetcher for that field. The annotation can specify the parent type name, and the field name:

@Controller
public class BookController {

    @SchemaMapping(typeName="Book", field="author")
    public Author getAuthor(Book book) {
        // ...
    }
}

The @SchemaMapping annotation can also leave out those attributes, in which case the field name defaults to the method name, while the type name defaults to the simple class name of the source/parent object injected into the method. For example, the below defaults to type "Book" and field "author":

@Controller
public class BookController {

    @SchemaMapping
    public Author author(Book book) {
        // ...
    }
}

The @SchemaMapping annotation can be declared at the class level to specify a default type name for all handler methods in the class.

@Controller
@SchemaMapping(typeName="Book")
public class BookController {

    // @SchemaMapping methods for fields of the "Book" type

}

@QueryMapping, @MutationMapping, and @SubscriptionMapping are meta annotations that are themselves annotated with @SchemaMapping and have the typeName preset to Query, Mutation, or Subscription respectively. Effectively, these are shortcut annotations for fields under the Query, Mutation, and Subscription types respectively. For example:

@Controller
public class BookController {

    @QueryMapping
    public Book bookById(@Argument Long id) {
        // ...
    }

    @MutationMapping
    public Book addBook(@Argument BookInput bookInput) {
        // ...
    }

    @SubscriptionMapping
    public Flux<Book> newPublications() {
        // ...
    }
}

@SchemaMapping handler methods have flexible signatures and can choose from a range of method arguments and return values..

6.2.1. Method Signature

Schema mapping handler methods can have any of the following method arguments:

Method Argument Description

@Argument

For access to a named field argument bound to a higher-level, typed Object.

See @Argument.

@Argument Map<String, Object>

For access to the raw argument value.

See @Argument.

ArgumentValue

For access to a named field argument bound to a higher-level, typed Object along with a flag to indicate if the input argument was omitted vs set to null.

See ArgumentValue.

@Arguments

For access to all field arguments bound to a higher-level, typed Object.

See @Arguments.

@Arguments Map<String, Object>

For access to the raw map of arguments.

@ProjectedPayload Interface

For access to field arguments through a project interface.

See @ProjectedPayload Interface.

"Source"

For access to the source (i.e. parent/container) instance of the field.

See Source.

Subrange and ScrollSubrange

For access to pagination arguments.

See Pagination, Scroll, Subrange.

Sort

For access to sort details.

See Pagination, Sort.

DataLoader

For access to a DataLoader in the DataLoaderRegistry.

See DataLoader.

@ContextValue

For access to an attribute from the main GraphQLContext in DataFetchingEnvironment.

@LocalContextValue

For access to an attribute from the local GraphQLContext in DataFetchingEnvironment.

GraphQLContext

For access to the context from the DataFetchingEnvironment.

java.security.Principal

Obtained from the Spring Security context, if available.

@AuthenticationPrincipal

For access to Authentication#getPrincipal() from the Spring Security context.

DataFetchingFieldSelectionSet

For access to the selection set for the query through the DataFetchingEnvironment.

Locale, Optional<Locale>

For access to the Locale from the DataFetchingEnvironment.

DataFetchingEnvironment

For direct access to the underlying DataFetchingEnvironment.

Schema mapping handler methods can return:

  • A resolved value of any type.

  • Mono and Flux for asynchronous value(s). Supported for controller methods and for any DataFetcher as described in Reactive DataFetcher.

  • java.util.concurrent.Callable to have the value(s) produced asynchronously. For this to work, AnnotatedControllerConfigurer must be configured with an Executor.

6.2.2. @Argument

In GraphQL Java, DataFetchingEnvironment provides access to a map of field-specific argument values. The values can be simple scalar values (e.g. String, Long), a Map of values for more complex input, or a List of values.

Use the @Argument annotation to have an argument bound to a target object and injected into the handler method. Binding is performed by mapping argument values to a primary data constructor of the expected method parameter type, or by using a default constructor to create the object and then map argument values to its properties. This is repeated recursively, using all nested argument values and creating nested target objects accordingly. For example:

@Controller
public class BookController {

    @QueryMapping
    public Book bookById(@Argument Long id) {
        // ...
    }

    @MutationMapping
    public Book addBook(@Argument BookInput bookInput) {
        // ...
    }
}
If the target object doesn’t have setters, and you can’t change that, you can use a property on AnnotatedControllerConfigurer to allow falling back on binding via direct field access.

By default, if the method parameter name is available (requires the -parameters compiler flag with Java 8+ or debugging info from the compiler), it is used to look up the argument. If needed, you can customize the name through the annotation, e.g. @Argument("bookInput").

The @Argument annotation does not have a "required" flag, nor the option to specify a default value. Both of these can be specified at the GraphQL schema level and are enforced by GraphQL Java.

If binding fails, a BindException is raised with binding issues accumulated as field errors where the field of each error is the argument path where the issue occurred.

You can use @Argument with a Map<String, Object> argument, to obtain the raw value of the argument. For example:

@Controller
public class BookController {

    @MutationMapping
    public Book addBook(@Argument Map<String, Object> bookInput) {
        // ...
    }
}
Prior to 1.2, @Argument Map<String, Object> returned the full arguments map if the annotation did not specify a name. After 1.2, @Argument with Map<String, Object> always returns the raw argument value, matching either to the name specified in the annotation, or to the parameter name. For access to the full arguments map, please use @Arguments instead.

6.2.3. ArgumentValue

By default, input arguments in GraphQL are nullable and optional, which means an argument can be set to the null literal, or not provided at all. This distinction is useful for partial updates with a mutation where the underlying data may also be, either set to null or not changed at all accordingly. When using @Argument there is no way to make such a distinction, because you would get null or an empty Optional in both cases.

If you want to know not whether a value was not provided at all, you can declare an ArgumentValue method parameter, which is a simple container for the resulting value, along with a flag to indicate whether the input argument was omitted altogether. You can use this instead of @Argument, in which case the argument name is determined from the method parameter name, or together with @Argument to specify the argument name.

For example:

@Controller
public class BookController {

    @MutationMapping
    public void addBook(ArgumentValue<BookInput> bookInput) {
        if (!bookInput.isOmitted()) {
            BookInput value = bookInput.value();
            // ...
        }
    }
}

ArgumentValue is also supported as a field within the object structure of an @Argument method parameter, either initialized via a constructor argument or via a setter, including as a field of an object nested at any level below the top level object.

6.2.4. @Arguments

Use the @Arguments annotation, if you want to bind the full arguments map onto a single target Object, in contrast to @Argument, which binds a specific, named argument.

For example, @Argument BookInput bookInput uses the value of the argument "bookInput" to initialize BookInput, while @Arguments uses the full arguments map and in that case, top-level arguments are bound to BookInput properties.

You can use @Arguments with a Map<String, Object> argument, to obtain the raw map of all argument values.

6.2.5. @ProjectedPayload Interface

As an alternative to using complete Objects with @Argument, you can also use a projection interface to access GraphQL request arguments through a well-defined, minimal interface. Argument projections are provided by Spring Data’s Interface projections when Spring Data is on the class path.

To make use of this, create an interface annotated with @ProjectedPayload and declare it as a controller method parameter. If the parameter is annotated with @Argument, it applies to an individual argument within the DataFetchingEnvironment.getArguments() map. When declared without @Argument, the projection works on top-level arguments in the complete arguments map.

For example:

@Controller
public class BookController {

    @QueryMapping
    public Book bookById(BookIdProjection bookId) {
        // ...
    }

    @MutationMapping
    public Book addBook(@Argument BookInputProjection bookInput) {
        // ...
    }
}

@ProjectedPayload
interface BookIdProjection {

    Long getId();
}

@ProjectedPayload
interface BookInputProjection {

    String getName();

    @Value("#{target.author + ' ' + target.name}")
    String getAuthorAndName();
}

6.2.6. Source

In GraphQL Java, the DataFetchingEnvironment provides access to the source (i.e. parent/container) instance of the field. To access this, simply declare a method parameter of the expected target type.

@Controller
public class BookController {

    @SchemaMapping
    public Author author(Book book) {
        // ...
    }
}

The source method argument also helps to determine the type name for the mapping. If the simple name of the Java class matches the GraphQL type, then there is no need to explicitly specify the type name in the @SchemaMapping annotation.

A @BatchMapping handler method can batch load all authors for a query, given a list of source/parent books objects.

6.2.7. Subrange

When there is a CursorStrategy bean in Spring configuration, controller methods support a Subrange<P> argument where <P> is a relative position converted from a cursor. For Spring Data, ScrollSubrange exposes ScrollPosition. For example:

@Controller
public class BookController {

    @QueryMapping
    public Window<Book> books(ScrollSubrange subrange) {
        ScrollPosition position = subrange.position().orElse(OffsetScrollPosition.initial())
        int count = subrange.count().orElse(20);
        // ...
    }

}

See Pagination for an overview of pagination and of built-in mechanisms.

6.2.8. Sort

When there is a SortStrategy bean in Spring configuration, controller methods support Sort as a method argument. For example:

@Controller
public class BookController {

    @QueryMapping
    public Window<Book> books(Optional<Sort> optionalSort) {
        Sort sort = optionalSort.orElse(Sort.by(..));
    }

}

6.2.9. DataLoader

When you register a batch loading function for an entity, as explained in Batch Loading, you can access the DataLoader for the entity by declaring a method argument of type DataLoader and use it to load the entity:

@Controller
public class BookController {

    public BookController(BatchLoaderRegistry registry) {
        registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
            // return Map<Long, Author>
        });
    }

    @SchemaMapping
    public CompletableFuture<Author> author(Book book, DataLoader<Long, Author> loader) {
        return loader.load(book.getAuthorId());
    }

}

By default, BatchLoaderRegistry uses the full class name of the value type (e.g. the class name for Author) for the key of the registration, and therefore simply declaring the DataLoader method argument with generic types provides enough information to locate it in the DataLoaderRegistry. As a fallback, the DataLoader method argument resolver will also try the method argument name as the key but typically that should not be necessary.

Note that for many cases with loading related entities, where the @SchemaMapping simply delegates to a DataLoader, you can reduce boilerplate by using a @BatchMapping method as described in the next section.

6.2.10. Validation

When a javax.validation.Validator bean is found, AnnotatedControllerConfigurer enables support for Bean Validation on annotated controller methods. Typically, the bean is of type LocalValidatorFactoryBean.

Bean validation lets you declare constraints on types:

public class BookInput {

    @NotNull
    private String title;

    @NotNull
    @Size(max=13)
    private String isbn;
}

You can then annotate a controller method parameter with @Valid to validate it before method invocation:

@Controller
public class BookController {

    @MutationMapping
    public Book addBook(@Argument @Valid BookInput bookInput) {
        // ...
    }
}

If an error occurs during validation, a ConstraintViolationException is raised. You can use the Exceptions chain to decide how to present that to clients by turning it into an error to include in the GraphQL response.

In addition to @Valid, you can also use Spring’s @Validated that allows specifying validation groups.

Bean validation is useful for @Argument, @Arguments, and @ProjectedPayload method parameters, but applies more generally to any method parameter.

Validation and Kotlin Coroutines

Hibernate Validator is not compatible with Kotlin Coroutine methods and fails when introspecting their method parameters. Please see spring-projects/spring-graphql#344 (comment) for links to relevant issues and a suggested workaround.

6.3. @BatchMapping

Batch Loading addresses the N+1 select problem through the use of an org.dataloader.DataLoader to defer the loading of individual entity instances, so they can be loaded together. For example:

@Controller
public class BookController {

    public BookController(BatchLoaderRegistry registry) {
        registry.forTypePair(Long.class, Author.class).registerMappedBatchLoader((authorIds, env) -> {
            // return Map<Long, Author>
        });
    }

    @SchemaMapping
    public CompletableFuture<Author> author(Book book, DataLoader<Long, Author> loader) {
        return loader.load(book.getAuthorId());
    }

}

For the straight-forward case of loading an associated entity, shown above, the @SchemaMapping method does nothing more than delegate to the DataLoader. This is boilerplate that can be avoided with a @BatchMapping method. For example:

@Controller
public class BookController {

    @BatchMapping
    public Mono<Map<Book, Author>> author(List<Book> books) {
        // ...
    }
}

The above becomes a batch loading function in the BatchLoaderRegistry where keys are Book instances and the loaded values their authors. In addition, a DataFetcher is also transparently bound to the author field of the type Book, which simply delegates to the DataLoader for authors, given its source/parent Book instance.

To be used as a unique key, Book must implement hashcode and equals.

By default, the field name defaults to the method name, while the type name defaults to the simple class name of the input List element type. Both can be customized through annotation attributes. The type name can also be inherited from a class level @SchemaMapping.

6.3.1. Method Signature

Batch mapping methods support the following arguments:

Method Argument Description

List<K>

The source/parent objects.

java.security.Principal

Obtained from Spring Security context, if available.

@ContextValue

For access to a value from the GraphQLContext of BatchLoaderEnvironment, which is the same context as the one from the DataFetchingEnvironment.

GraphQLContext

For access to the context from the BatchLoaderEnvironment, which is the same context as the one from the DataFetchingEnvironment.

BatchLoaderEnvironment

The environment that is available in GraphQL Java to a org.dataloader.BatchLoaderWithContext.

Batch mapping methods can return:

Return Type Description

Mono<Map<K,V>>

A map with parent objects as keys, and batch loaded objects as values.

Flux<V>

A sequence of batch loaded objects that must be in the same order as the source/parent objects passed into the method.

Map<K,V>, Collection<V>

Imperative variants, e.g. without remote calls to make.

Callable<Map<K,V>>, Callable<Collection<V>>

Imperative variants to be invoked asynchronously. For this to work, AnnotatedControllerConfigurer must be configured with an Executor.

6.4. @GraphQlExceptionHandler

Use @GraphQlExceptionHandler methods to handle exceptions from data fetching with a flexible method signature. When declared in a controller, exception handler methods apply to exceptions from the same controller:

@Controller
public class BookController {

    @QueryMapping
    public Book bookById(@Argument Long id) {
        // ...
    }

    @GraphQlExceptionHandler
    public GraphQLError handle(BindException ex) {
        return GraphQLError.newError().errorType(ErrorType.BAD_REQUEST).message("...").build();
    }

}

When declared in an @ControllerAdvice, exception handler methods apply across controllers:

@ControllerAdvice
public class GlobalExceptionHandler {

    @GraphQlExceptionHandler
    public GraphQLError handle(BindException ex) {
        return GraphQLError.newError().errorType(ErrorType.BAD_REQUEST).message("...").build();
    }

}

Exception handling via @GraphQlExceptionHandler methods is applied automatically to controller invocations. To handle exceptions from other graphql.schema.DataFetcher implementations, not based on controller methods, obtain a DataFetcherExceptionResolver from AnnotatedControllerConfigurer, and register it in GraphQlSource.Builder as a DataFetcherExceptionResolver.

6.4.1. Method Signature

Exception handler methods support a flexible method signature with method arguments resolved from a DataFetchingEnvironment, and matching to those of @SchemaMapping methods.

Supported return types are listed below:

Return Type Description

graphql.GraphQLError

Resolve the exception to a single field error.

Collection<GraphQLError>

Resolve the exception to multiple field errors.

void

Resolve the exception without response errors.

Object

Resolve the exception to a single error, to multiple errors, or none. The return value must be GraphQLError, Collection<GraphQLError>, or null.

Mono<T>

For asynchronous resolution where <T> is one of the supported, synchronous, return types.

7. Security

The path to a Web GraphQL endpoint can be secured with HTTP URL security to ensure that only authenticated users can access it. This does not, however, differentiate among different GraphQL requests on such a shared endpoint on a single URL.

To apply more fine-grained security, add Spring Security annotations such as @PreAuthorize or @Secured to service methods involved in fetching specific parts of the GraphQL response. This should work due to Context Propagation that aims to make Security, and other context, available at the data fetching level.

The 1.0.x branch of this repository contains samples for Spring MVC and for WebFlux.

8. Observability

Observability support with Micrometer is directly instrumented in Spring for GraphQL. This enables both metrics and traces for GraphQL requests and "non-trivial" data fetching operations. Because the GraphQL engine operates on top of a transport layer, you should also expect observations from the transport, if supported in Spring Framework.

Observations are only published if an ObservationRegistry is configured in the application. You can learn more about configuring the observability infrastructure in Spring Boot. If you would like to customize the metadata produced with the GraphQL observations, you can configure a custom convention on the instrumentation directly. If your application is using Spring Boot, contributing the custom convention as a bean is the preferred way.

8.1. Server Requests instrumentation

GraphQL Server Requests observations are created with the name "graphql.request" for traditional and Reactive applications and above all supported transports. This instrumentation assumes that any parent observation must be set as the current one on the GraphQL context with the well-known "micrometer.observation" key. For trace propagation across network boundaries, a separate instrumentation at the transport level must be in charge. In the case of HTTP, Spring Framework has dedicated instrumentation that takes care of trace propagation.

Applications need to configure the org.springframework.graphql.observation.GraphQlObservationInstrumentation instrumentation in their application. It is using the org.springframework.graphql.observation.DefaultExecutionRequestObservationConvention by default, backed by the ExecutionRequestObservationContext.

By default, the following KeyValues are created:

Table 1. Low cardinality Keys

Name

Description

graphql.operation (required)

GraphQL Operation name.

graphql.outcome (required)

Outcome of the GraphQL request.

The graphql.operation KeyValue will use the custom name of the provided query, or the standard name for the operation if none ("query", "mutation" or "subscription"). The graphql.outcome KeyValue will be "SUCCESS" if a valid GraphQL response has been sent, "REQUEST_ERROR" if the request could not be parsed, or "INTERNAL_ERROR" if no valid GraphQL response could be produced.

Table 2. High cardinality Keys

Name

Description

graphql.execution.id (required)

graphql.execution.ExecutionId of the GraphQL request.

8.2. DataFetcher instrumentation

GraphQL DataFetcher observations are created with the name "graphql.datafetcher", only for data fetching operations that are considered as "non trivial" (property fetching on a Java object is a trivial operation). Applications need to configure the org.springframework.graphql.observation.GraphQlObservationInstrumentation instrumentation in their application. It is using the org.springframework.graphql.observation.DefaultDataFetcherObservationConvention by default, backed by the DataFetcherObservationContext.

By default, the following KeyValues are created:

Table 3. Low cardinality Keys

Name

Description

graphql.error.type (required)

Class name of the data fetching error

graphql.field.name (required)

Name of the field being fetched.

graphql.outcome (required)

Outcome of the GraphQL data fetching operation, "SUCCESS" or "ERROR".

Table 4. High cardinality Keys

Name

Description

graphql.field.path (required)

Path to the field being fetched (for example, "/bookById").

9. GraalVM Native support

Spring Framework 6.0 introduced the support infrastructure for compiling Spring applications to GraalVM Native images. If you are not familiar with GraalVM in general, how this differs from applications deployed on the JVM and what it means for Spring application, please refer to the dedicated Spring Boot 3.0 GraalVM Native Image support documentation. Spring Boot also documents the know limitations with the GraalVM support in Spring.

9.1. GraphQL Java metadata

Since the static analysis of your application is done at build time, GraalVM might need extra hints if your application is looking up static resources, performing reflection or creating JDK proxies at runtime.

GraphQL Java is performing three tasks at runtime that Native Images are sensible to:

  1. Loading resource bundles for message internationalization

  2. Some reflection on internal types for schema inspection

  3. Reflection on Java types that your application registers with the schema. This happens for example when GraphQL Java is fetching properties from application types

The first two items are handled via reachability metadata that has been contributed by the Spring team to the GraalVM reachability metadata repository. This metadata is automatically fetched by the native compilation tool when building an application that depends on GraphQL Java. This doesn’t cover our third item in the list, as those types are provided by the application itself and must be discovered by another mean.

9.2. Native Server applications support

In typical Spring for GraphQL applications, Java types tied to the GraphQL schema are exposed in @Controller method signatures as parameters or return types. During the Ahead Of Time processing phase of the build, Spring or GraphQL will use its o.s.g.data.method.annotation.support.SchemaMappingBeanFactoryInitializationAotProcessor to discover the relevant types and register reachability metadata accordingly. This is all done automatically for you if you are building a Spring Boot application with GraalVM support.

If your application is "manually" registering data fetchers, some types are not discoverable as a result. You should then register them with Spring Framework’s @RegisterReflectionForBinding:

import graphql.schema.DataFetcher;

import org.springframework.aot.hint.annotation.RegisterReflectionForBinding;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.graphql.data.query.QuerydslDataFetcher;
import org.springframework.graphql.execution.RuntimeWiringConfigurer;

@Configuration
@RegisterReflectionForBinding(Book.class) (3)
public class GraphQlConfiguration {

    @Bean
    RuntimeWiringConfigurer customWiringConfigurer(BookRepository bookRepository) { (1)
        DataFetcher<Book> dataFetcher = QuerydslDataFetcher.builder(bookRepository).single();
        return wiringBuilder -> wiringBuilder
                .type("Query", builder -> builder.dataFetcher("book", dataFetcher)); (2)
    }

}
1 This application declares a RuntimeWiringConfigurer that "manually" adds a DataFetcher
2 Through this DataFetcher, the BookRepository will expose a Book type
3 @RegisterReflectionForBinding will register the relevant hints for the Book type and all types exposed as fields

9.3. Client support

The GraphQlClient is not necessarily present as a bean in the application context and it does not expose the Java types used in the schema in method signatures. The AotProcessor strategy described in the section above cannot be used as a result. For client support, Spring for GraphQL embeds the relevant reachability metadata for the client infrastructure. When it comes to Java types used by the application, applications should use a similar strategy as "manual" data fetchers using @RegisterReflectionForBinding:

import reactor.core.publisher.Mono;

import org.springframework.aot.hint.annotation.RegisterReflectionForBinding;
import org.springframework.graphql.client.GraphQlClient;
import org.springframework.stereotype.Component;

@Component
@RegisterReflectionForBinding(Project.class) (2)
public class ProjectService {

    private final GraphQlClient graphQlClient;

    public ProjectService(GraphQlClient graphQlClient) {
        this.graphQlClient = graphQlClient;
    }

    public Mono<Project> project(String projectSlug) {
        String document = """
                query projectWithReleases($projectSlug: ID!) {
                    project(slug: $projectSlug) {
                        name
                        releases {
                            version
                        }
                    }
                }
                """;

        return this.graphQlClient.document(document)
                .variable("projectSlug", projectSlug)
                .retrieve("project")
                .toEntity(Project.class); (1)
    }
}
1 In a Native image, we need to ensure that reflection can be performed on Project at runtime
2 @RegisterReflectionForBinding will register the relevant hints for the Project type and all types exposed as fields

10. Client

Spring for GraphQL includes client support for executing GraphQL requests over HTTP, WebSocket, and RSocket.

10.1. GraphQlClient

GraphQlClient is a contract that declares a common workflow for GraphQL requests that is independent of the underlying transport. That means requests are executed with the same API no matter what the underlying transport, and anything transport specific is configured at build time.

To create a GraphQlClient you need one of the following extensions:

Each defines a Builder with options relevant to the transport. All builders extend from a common, base GraphQlClient Builder with options relevant to all extensions.

Once you have a GraphQlClient you can begin to make requests.

10.1.1. HTTP

HttpGraphQlClient uses WebClient to execute GraphQL requests over HTTP.

WebClient webClient = ... ;
HttpGraphQlClient graphQlClient = HttpGraphQlClient.create(webClient);

Once HttpGraphQlClient is created, you can begin to execute requests using the same API, independent of the underlying transport. If you need to change any transport specific details, use mutate() on an existing HttpGraphQlClient to create a new instance with customized settings:

WebClient webClient = ... ;

HttpGraphQlClient graphQlClient = HttpGraphQlClient.builder(webClient)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

// Perform requests with graphQlClient...

HttpGraphQlClient anotherGraphQlClient = graphQlClient.mutate()
        .headers(headers -> headers.setBasicAuth("peter", "..."))
        .build();

// Perform requests with anotherGraphQlClient...

10.1.2. WebSocket

WebSocketGraphQlClient executes GraphQL requests over a shared WebSocket connection. It is built using the WebSocketClient from Spring WebFlux and you can create it as follows:

String url = "wss://localhost:8080/graphql";
WebSocketClient client = new ReactorNettyWebSocketClient();

WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client).build();

In contrast to HttpGraphQlClient, the WebSocketGraphQlClient is connection oriented, which means it needs to establish a connection before making any requests. As you begin to make requests, the connection is established transparently. Alternatively, use the client’s start() method to establish the connection explicitly before any requests.

In addition to being connection-oriented, WebSocketGraphQlClient is also multiplexed. It maintains a single, shared connection for all requests. If the connection is lost, it is re-established on the next request or if start() is called again. You can also use the client’s stop() method which cancels in-progress requests, closes the connection, and rejects new requests.

Use a single WebSocketGraphQlClient instance for each server in order to have a single, shared connection for all requests to that server. Each client instance establishes its own connection and that is typically not the intent for a single server.

Once WebSocketGraphQlClient is created, you can begin to execute requests using the same API, independent of the underlying transport. If you need to change any transport specific details, use mutate() on an existing WebSocketGraphQlClient to create a new instance with customized settings:

URI url = ... ;
WebSocketClient client = ... ;

WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

// Use graphQlClient...

WebSocketGraphQlClient anotherGraphQlClient = graphQlClient.mutate()
        .headers(headers -> headers.setBasicAuth("peter", "..."))
        .build();

// Use anotherGraphQlClient...
Interceptor

The GraphQL over WebSocket protocol defines a number of connection oriented messages in addition to executing requests. For example, a client sends "connection_init" and the server responds with "connection_ack" at the start of a connection.

For WebSocket transport specific interception, you can create a WebSocketGraphQlClientInterceptor:

static class MyInterceptor implements WebSocketGraphQlClientInterceptor {

    @Override
    public Mono<Object> connectionInitPayload() {
        // ... the "connection_init" payload to send
    }

    @Override
    public Mono<Void> handleConnectionAck(Map<String, Object> ackPayload) {
        // ... the "connection_ack" payload received
    }

}

Register the above interceptor as any other GraphQlClientInterceptor and use it also to intercept GraphQL requests, but note there can be at most one interceptor of type WebSocketGraphQlClientInterceptor.

10.1.3. RSocket

RSocketGraphQlClient uses RSocketRequester to execute GraphQL requests over RSocket requests.

URI uri = URI.create("wss://localhost:8080/rsocket");
WebsocketClientTransport transport = WebsocketClientTransport.create(url);

RSocketGraphQlClient client = RSocketGraphQlClient.builder()
        .clientTransport(transport)
        .build();

In contrast to HttpGraphQlClient, the RSocketGraphQlClient is connection oriented, which means it needs to establish a session before making any requests. As you begin to make requests, the session is established transparently. Alternatively, use the client’s start() method to establish the session explicitly before any requests.

RSocketGraphQlClient is also multiplexed. It maintains a single, shared session for all requests. If the session is lost, it is re-established on the next request or if start() is called again. You can also use the client’s stop() method which cancels in-progress requests, closes the session, and rejects new requests.

Use a single RSocketGraphQlClient instance for each server in order to have a single, shared session for all requests to that server. Each client instance establishes its own connection and that is typically not the intent for a single server.

Once RSocketGraphQlClient is created, you can begin to execute requests using the same API, independent of the underlying transport.

10.1.4. Builder

GraphQlClient defines a parent Builder with common configuration options for the builders of all extensions. Currently, it has lets you configure:

  • DocumentSource strategy to load the document for a request from a file

  • Interception of executed requests

10.2. Requests

Once you have a GraphQlClient, you can begin to perform requests via retrieve() or execute() where the former is only a shortcut for the latter.

10.2.1. Retrieve

The below retrieves and decodes the data for a query:

String document = "{" +
        "  project(slug:\"spring-framework\") {" +
        "   name" +
        "   releases {" +
        "     version" +
        "   }"+
        "  }" +
        "}";

Mono<Project> projectMono = graphQlClient.document(document) (1)
        .retrieve("project") (2)
        .toEntity(Project.class); (3)
1 The operation to perform.
2 The path under the "data" key in the response map to decode from.
3 Decode the data at the path to the target type.

The input document is a String that could be a literal or produced through a code generated request object. You can also define documents in files and use a Document Source to resole them by file name.

The path is relative to the "data" key and uses a simple dot (".") separated notation for nested fields with optional array indices for list elements, e.g. "project.name" or "project.releases[0].version".

Decoding can result in FieldAccessException if the given path is not present, or the field value is null and has an error. FieldAccessException provides access to the response and the field:

Mono<Project> projectMono = graphQlClient.document(document)
        .retrieve("project")
        .toEntity(Project.class)
        .onErrorResume(FieldAccessException.class, ex -> {
            ClientGraphQlResponse response = ex.getResponse();
            // ...
            ClientResponseField field = ex.getField();
            // ...
        });

10.2.2. Execute

Retrieve is only a shortcut to decode from a single path in the response map. For more control, use the execute method and handle the response:

For example:

Mono<Project> projectMono = graphQlClient.document(document)
        .execute()
        .map(response -> {
            if (!response.isValid()) {
                // Request failure... (1)
            }

            ClientResponseField field = response.field("project");
            if (!field.hasValue()) {
                if (field.getError() != null) {
                    // Field failure... (2)
                }
                else {
                    // Optional field set to null... (3)
                }
            }

            return field.toEntity(Project.class); (4)
        });
1 The response does not have data, only errors
2 Field that is null and has an associated error
3 Field that was set to null by its DataFetcher
4 Decode the data at the given path

10.2.3. Document Source

The document for a request is a String that may be defined in a local variable or constant, or it may be produced through a code generated request object.

You can also create document files with extensions .graphql or .gql under "graphql-documents/" on the classpath and refer to them by file name.

For example, given a file called projectReleases.graphql in src/main/resources/graphql-documents, with content:

src/main/resources/graphql-documents/projectReleases.graphql
query projectReleases($slug: ID!) {
    project(slug: $slug) {
        name
        releases {
            version
        }
    }
}

You can then:

Mono<Project> projectMono = graphQlClient.documentName("projectReleases") (1)
        .variable("slug", "spring-framework") (2)
        .retrieve()
        .toEntity(Project.class);
1 Load the document from "projectReleases.graphql"
2 Provide variable values.

The "JS GraphQL" plugin for IntelliJ supports GraphQL query files with code completion.

You can use the GraphQlClient Builder to customize the DocumentSource for loading documents by names.

10.3. Subscription Requests

GraphQlClient can execute subscriptions over transports that support it. Currently, only the WebSocket transport supports GraphQL streams, so you’ll need to create a WebSocketGraphQlClient.

10.3.1. Retrieve

To start a subscription stream, use retrieveSubscription which is similar to retrieve for a single response but returning a stream of responses, each decoded to some data:

Flux<String> greetingFlux = client.document("subscription { greetings }")
        .retrieveSubscription("greeting")
        .toEntity(String.class);

A subscription stream may end with:

  • SubscriptionErrorException if the server ends the subscription with an explicit "error" message that contains one or more GraphQL errors. The exception provides access to the GraphQL errors decoded from that message.

  • GraphQlTransportException such as WebSocketDisconnectedException if the underlying connection is closed or lost in which case you can use the retry operator to reestablish the connection and start the subscription again.

10.3.2. Execute

Retrieve is only a shortcut to decode from a single path in each response map. For more control, use the executeSubscription method and handle each response directly:

Flux<String> greetingFlux = client.document("subscription { greetings }")
        .executeSubscription()
        .map(response -> {
            if (!response.isValid()) {
                // Request failure...
            }

            ClientResponseField field = response.field("project");
            if (!field.hasValue()) {
                if (field.getError() != null) {
                    // Field failure...
                }
                else {
                    // Optional field set to null... (3)
                }
            }

            return field.toEntity(String.class)
        });

10.4. Interception

You create a GraphQlClientInterceptor to intercept all requests through a client:

static class MyInterceptor implements GraphQlClientInterceptor {

    @Override
    public Mono<ClientGraphQlResponse> intercept(ClientGraphQlRequest request, Chain chain) {
        // ...
        return chain.next(request);
    }

    @Override
    public Flux<ClientGraphQlResponse> interceptSubscription(ClientGraphQlRequest request, SubscriptionChain chain) {
        // ...
        return chain.next(request);
    }

}

Once the interceptor is created, register it through the client builder:

URI url = ... ;
WebSocketClient client = ... ;

WebSocketGraphQlClient graphQlClient = WebSocketGraphQlClient.builder(url, client)
        .interceptor(new MyInterceptor())
        .build();

11. GraphiQL

GraphiQL is a graphical interactive in-browser GraphQL IDE. It is very popular amongst developers as it makes it easy to explore and interactively develop GraphQL APIs. During development, a stock GraphiQL integration is often enough to help developers work on an API. In production, applications can require a custom GraphiQL build, that ships with a company logo or specific authentication support.

Spring for GraphQL ships with a stock GraphiQL index.html page that uses static resources hosted on the unpkg.com CDN. Spring Boot applications can easily enable this page with a configuration property.

Your application may need a custom GraphiQL build if it requires a setup that doesn’t rely on a CDN, or if you wish to customize the user interface. This can be done in two steps:

  1. Configure and compile a GraphiQL build

  2. Expose the built GraphiQL instance through the Spring web infrastructure

11.1. Creating a custom GraphiQL build

This part is generally outside of the scope of this documentation, as there are several options for custom builds. You will find more information in the official GraphiQL documentation. You can choose to copy the build result directly in your application resources. Alternatively, you can integrate the JavaScript build in your project as a separate module by leveraging Node.js Gradle or Maven build plugins.

11.2. Exposing a GraphiQL instance

Once a GraphiQL build is available on the classpath, you can expose it as an endpoint with the functional web frameworks.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
import org.springframework.core.io.ClassPathResource;
import org.springframework.graphql.server.webmvc.GraphiQlHandler;
import org.springframework.web.servlet.function.RouterFunction;
import org.springframework.web.servlet.function.RouterFunctions;
import org.springframework.web.servlet.function.ServerResponse;

@Configuration
public class GraphiQlConfiguration {

    @Bean
    @Order(0)
    public RouterFunction<ServerResponse> graphiQlRouterFunction() {
        RouterFunctions.Builder builder = RouterFunctions.route();
        ClassPathResource graphiQlPage = new ClassPathResource("graphiql/index.html"); (1)
        GraphiQlHandler graphiQLHandler = new GraphiQlHandler("/graphql", "", graphiQlPage); (2)
        builder = builder.GET("/graphiql", graphiQLHandler::handleRequest); (3)
        return builder.build(); (4)
    }
}
1 Load the GraphiQL page from the classpath (here, we are using the version shipped with Spring for GraphQL)
2 Configure a web handler for processing HTTP requests; you can implement a custom HandlerFunction depending on your use case
3 Finally, map the handler to a specific HTTP endpoint
4 Expose this new route through a RouterFunction bean

You might also need to configure your application to serve the relevant static resources.

12. Testing

Spring for GraphQL provides dedicated support for testing GraphQL requests over HTTP, WebSocket, and RSocket, as well as for testing directly against a server.

To make use of this, add spring-graphql-test to your build:

Gradle
dependencies {
    // ...
    testImplementation 'org.springframework.graphql:spring-graphql-test:1.2.0'
}
Maven
<dependencies>
    <!-- ... -->
    <dependency>
        <groupId>org.springframework.graphql</groupId>
        <artifactId>spring-graphql-test</artifactId>
        <version>1.2.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

12.1. GraphQlTester

GraphQlTester is a contract that declares a common workflow for testing GraphQL requests that is independent of the underlying transport. That means requests are tested with the same API no matter what the underlying transport, and anything transport specific is configured at build time.

To create a GraphQlTester that performs requests through a client, you need one of the following extensions:

To create a GraphQlTester that performs tests on the server side, without a client:

Each defines a Builder with options relevant to the transport. All builders extend from a common, base GraphQlTester Builder with options relevant to all extensions.

12.1.1. HTTP

HttpGraphQlTester uses WebTestClient to execute GraphQL requests over HTTP, with or without a live server, depending on how WebTestClient is configured.

To test in Spring WebFlux, without a live server, point to your Spring configuration that declares the GraphQL HTTP endpoint:

ApplicationContext context = ... ;

WebTestClient client =
        WebTestClient.bindToApplicationContext(context)
                .configureClient()
                .baseUrl("/graphql")
                .build();

HttpGraphQlTester tester = HttpGraphQlTester.create(client);

To test in Spring MVC, without a live server, do the same using MockMvcWebTestClient:

ApplicationContext context = ... ;

WebTestClient client =
        MockMvcWebTestClient.bindToApplicationContext(context)
                .configureClient()
                .baseUrl("/graphql")
                .build();

HttpGraphQlTester tester = HttpGraphQlTester.create(client);

Or to test against a live server running on a port:

WebTestClient client =
        WebTestClient.bindToServer()
                .baseUrl("http://localhost:8080/graphql")
                .build();

HttpGraphQlTester tester = HttpGraphQlTester.create(client);

Once HttpGraphQlTester is created, you can begin to execute requests using the same API, independent of the underlying transport. If you need to change any transport specific details, use mutate() on an existing HttpSocketGraphQlTester to create a new instance with customized settings:

HttpGraphQlTester tester = HttpGraphQlTester.builder(clientBuilder)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

// Use tester...

HttpGraphQlTester anotherTester = tester.mutate()
        .headers(headers -> headers.setBasicAuth("peter", "..."))
        .build();

// Use anotherTester...

12.1.2. WebSocket

WebSocketGraphQlTester executes GraphQL requests over a shared WebSocket connection. It is built using the WebSocketClient from Spring WebFlux and you can create it as follows:

String url = "http://localhost:8080/graphql";
WebSocketClient client = new ReactorNettyWebSocketClient();

WebSocketGraphQlTester tester = WebSocketGraphQlTester.builder(url, client).build();

WebSocketGraphQlTester is connection oriented and multiplexed. Each instance establishes its own single, shared connection for all requests. Typically, you’ll want to use a single instance only per server.

Once WebSocketGraphQlTester is created, you can begin to execute requests using the same API, independent of the underlying transport. If you need to change any transport specific details, use mutate() on an existing WebSocketGraphQlTester to create a new instance with customized settings:

URI url = ... ;
WebSocketClient client = ... ;

WebSocketGraphQlTester tester = WebSocketGraphQlTester.builder(url, client)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

// Use tester...

WebSocketGraphQlTester anotherTester = tester.mutate()
        .headers(headers -> headers.setBasicAuth("peter", "..."))
        .build();

// Use anotherTester...

WebSocketGraphQlTester provides a stop() method that you can use to have the WebSocket connection closed, e.g. after a test runs.

12.1.3. RSocket

RSocketGraphQlTester uses RSocketRequester from spring-messaging to execute GraphQL requests over RSocket:

URI uri = URI.create("wss://localhost:8080/rsocket");
WebsocketClientTransport transport = WebsocketClientTransport.create(url);

RSocketGraphQlTester client = RSocketGraphQlTester.builder()
        .clientTransport(transport)
        .build();

RSocketGraphQlTester is connection oriented and multiplexed. Each instance establishes its own single, shared session for all requests. Typically, you’ll want to use a single instance only per server. You can use the stop() method on the tester to close the session explicitly.

Once RSocketGraphQlTester is created, you can begin to execute requests using the same API, independent of the underlying transport.

12.1.4. GraphQlService

Many times it’s enough to test GraphQL requests on the server side, without the use of a client to send requests over a transport protocol. To test directly against a ExecutionGraphQlService, use the ExecutionGraphQlServiceTester extension:

GraphQlService service = ... ;
ExecutionGraphQlServiceTester tester = ExecutionGraphQlServiceTester.create(service);

Once ExecutionGraphQlServiceTester is created, you can begin to execute requests using the same API, independent of the underlying transport.

ExecutionGraphQlServiceTester.Builder provides an option to customize ExecutionInput details:

GraphQlService service = ... ;
ExecutionGraphQlServiceTester tester = ExecutionGraphQlServiceTester.builder(service)
        .configureExecutionInput((executionInput, builder) -> builder.executionId(id).build())
        .build();

12.1.5. WebGraphQlHandler

The GraphQlService extension lets you test on the server side, without a client. However, in some cases it’s useful to involve server side transport handling with given mock transport input.

The WebGraphQlTester extension lets you processes request through the WebGraphQlInterceptor chain before handing off to ExecutionGraphQlService for request execution:

WebGraphQlHandler handler = ... ;
WebGraphQlTester tester = WebGraphQlTester.create(handler);

The builder for this extension allows you to define HTTP request details:

WebGraphQlHandler handler = ... ;

WebGraphQlTester tester = WebGraphQlTester.builder(handler)
        .headers(headers -> headers.setBasicAuth("joe", "..."))
        .build();

Once WebGraphQlServiceTester is created, you can begin to execute requests using the same API, independent of the underlying transport.

12.1.6. Builder

GraphQlTester defines a parent Builder with common configuration options for the builders of all extensions. It lets you configure the following:

  • errorFilter - a predicate to suppress expected errors, so you can inspect the data of the response.

  • documentSource - a strategy for loading the document for a request from a file on the classpath or from anywhere else.

  • responseTimeout - how long to wait for request execution to complete before timing out.

12.2. Requests

Once you have a GraphQlTester, you can begin to test requests. The below executes a query for a project and uses JsonPath to extract project release versions from the response:

String document = "{" +
        "  project(slug:\"spring-framework\") {" +
        "   releases {" +
        "     version" +
        "   }"+
        "  }" +
        "}";

graphQlTester.document(document)
        .execute()
        .path("project.releases[*].version")
        .entityList(String.class)
        .hasSizeGreaterThan(1);

The JsonPath is relative to the "data" section of the response.

You can also create document files with extensions .graphql or .gql under "graphql-test/" on the classpath and refer to them by file name.

For example, given a file called projectReleases.graphql in src/main/resources/graphql-test, with content:

query projectReleases($slug: ID!) {
    project(slug: $slug) {
        releases {
            version
        }
    }
}

You can then use:

graphQlTester.documentName("projectReleases") (1)
        .variable("slug", "spring-framework") (2)
        .execute()
        .path("project.releases[*].version")
        .entityList(String.class)
        .hasSizeGreaterThan(1);
1 Refer to the document in the file named "project".
2 Set the slug variable.

The "JS GraphQL" plugin for IntelliJ supports GraphQL query files with code completion.

If a request does not have any response data, e.g. mutation, use executeAndVerify instead of execute to verify there are no errors in the response:

graphQlTester.query(query).executeAndVerify();

See Errors for more details on error handling.

12.2.1. Nested Paths

By default, paths are relative to the "data" section of the GraphQL response. You can also nest down to a path, and inspect multiple paths relative to it as follows:

graphQlTester.document(document)
        .execute()
        .path("project", project -> project (1)
            .path("name").entity(String.class).isEqualTo("spring-framework")
            .path("releases[*].version").entityList(String.class).hasSizeGreaterThan(1));
1 Use a callback to inspect paths relative to "project".

12.3. Subscriptions

To test subscriptions, call executeSubscription instead of execute to obtain a stream of responses and then use StepVerifier from Project Reactor to inspect the stream:

Flux<String> greetingFlux = tester.document("subscription { greetings }")
        .executeSubscription()
        .toFlux("greetings", String.class);  // decode at JSONPath

StepVerifier.create(greetingFlux)
        .expectNext("Hi")
        .expectNext("Bonjour")
        .expectNext("Hola")
        .verifyComplete();

Subscriptions are supported only with WebSocketGraphQlTester, or with the server side GraphQlService and WebGraphQlHandler extensions.

12.4. Errors

When you use verify(), any errors under the "errors" key in the response will cause an assertion failure. To suppress a specific error, use the error filter before verify():

graphQlTester.query(query)
        .execute()
        .errors()
        .filter(error -> ...)
        .verify()
        .path("project.releases[*].version")
        .entityList(String.class)
        .hasSizeGreaterThan(1);

You can register an error filter at the builder level, to apply to all tests:

WebGraphQlTester graphQlTester = WebGraphQlTester.builder(client)
        .errorFilter(error -> ...)
        .build();

If you want to verify that an error does exist, and in contrast to filter, throw an assertion error if it doesn’t, then use exepect instead:

graphQlTester.query(query)
        .execute()
        .errors()
        .expect(error -> ...)
        .verify()
        .path("project.releases[*].version")
        .entityList(String.class)
        .hasSizeGreaterThan(1);

You can also inspect all errors through a Consumer, and doing so also marks them as filtered, so you can then also inspect the data in the response:

graphQlTester.query(query)
        .execute()
        .errors()
        .satisfy(errors -> {
            // ...
        });

13. Boot Starter

Spring Boot provides a starter for building GraphQL applications with Spring for GraphQL. For version information, see the Spring for GraphQL Versions wiki page.

The easiest way to get started is via start.spring.io by selecting "Spring for GraphQL" along with an underlying transport such as Spring MVC of WebFlux over HTTP or WebSocket, or over RSocket. Refer to the Spring for GraphQL Starter section in the Spring Boot reference for details on supported transports, auto-configuration related features, and more. For testing support, see Auto-Configured GraphQL Tests.

For further reference, check the following GraphQL related:

14. Samples

Check out the "Building a GraphQL service" Getting Started Guide.

In addition, the 1.0.x branch of this repository contains sample applications for various scenarios. Those samples do not exist in the main branch and are planned to be moved out into a separate repository. To run those samples, check out the 1.0.x branch run their main application classes from your IDE, or from the command line:

$ ./gradlew :samples:{sample-directory-name}:bootRun