graphql-java — Production-Grade GraphQL Engine for the JVM

Introduction

graphql-java is the foundational GraphQL engine for the Java ecosystem, providing the core library that most JVM-based GraphQL frameworks build upon. It handles the full lifecycle of a GraphQL request: parsing the query document, validating it against a schema, and executing it by calling data fetchers for each field. Spring for GraphQL, Netflix DGS, and many other frameworks use graphql-java as their underlying execution engine.

What graphql-java Does

• Parses GraphQL schema definitions (SDL) and query documents into an abstract syntax tree
• Validates queries against the schema using the full set of rules from the GraphQL specification
• Executes queries by dispatching field resolution to user-defined data fetcher functions
• Supports batched data loading through tight integration with the DataLoader pattern
• Provides instrumentation hooks for monitoring, tracing, and custom execution behavior

Architecture Overview

graphql-java is structured around a pipeline: parse, validate, execute. The parser converts SDL and query strings into AST nodes. The schema generator combines type definitions with runtime wiring (data fetchers and type resolvers) to produce an executable schema. During execution, the engine walks the query AST and invokes data fetchers for each field. Data fetchers return CompletableFuture values, enabling asynchronous and batched resolution. An instrumentation API wraps each step, allowing APM tools and custom logic to hook into parsing, validation, field resolution, and completion.

Self-Hosting & Configuration

• Add the Maven or Gradle dependency to your JVM project — no native libraries required
• Define your schema using SDL files or build it programmatically with the Java API
• Wire data fetchers to fields using RuntimeWiring to connect schema fields to your data layer
• Enable DataLoader for batched and cached data fetching to avoid the N+1 problem
• Integrate with Spring Boot via Spring for GraphQL, or with any HTTP framework using the execution result

Key Features

• Full GraphQL specification compliance including queries, mutations, subscriptions, and introspection
• Asynchronous execution using CompletableFuture for non-blocking data fetcher resolution
• Built-in DataLoader support for batching and caching field-level data access
• Instrumentation API for APM integration, query complexity analysis, and field-level metrics
• Schema transformation utilities for federation, stitching, and dynamic schema modification

Comparison with Similar Tools

• Spring for GraphQL — a Spring integration layer that uses graphql-java as its execution engine; graphql-java is the standalone core library
• Netflix DGS — a framework built on graphql-java that adds annotation-based schema wiring and testing utilities; graphql-java provides the underlying engine
• graphql-js — the JavaScript reference implementation; graphql-java is the equivalent for the JVM with Java-idiomatic APIs
• Sangria — the Scala GraphQL library; graphql-java targets Java with broader ecosystem adoption on the JVM
• graphql-kotlin — an ExpediaGroup library that adds Kotlin DSL sugar on top of graphql-java concepts

FAQ

Q: Is graphql-java the same as Spring for GraphQL? A: No. graphql-java is the low-level execution engine. Spring for GraphQL is a higher-level framework that integrates graphql-java with Spring Boot, providing annotations, auto-configuration, and Spring-specific features.

Q: How do I prevent expensive or abusive queries? A: graphql-java provides query complexity analysis via instrumentation. You can set a maximum query depth, field count, or calculated complexity score and reject queries that exceed the limit before execution.

Q: Does graphql-java support GraphQL Federation? A: The core library provides the building blocks. For full Apollo Federation support, use the apollo-federation-jvm library or Netflix DGS, both of which extend graphql-java with federation directives and entity resolution.

Q: How does async execution work? A: Data fetchers can return CompletableFuture objects. graphql-java automatically handles the async resolution, composing futures across the query tree and assembling the result when all futures complete.

Sources

• https://github.com/graphql-java/graphql-java
• https://www.graphql-java.com/