0Pricing
Spring Boot 4 Complete Guide · Lesson

Data Fetchers and Argument Binding

Implement @QueryMapping and @MutationMapping handlers with argument and input binding.

Data Fetchers and Argument Binding is a free Spring Boot 4 Complete Guide lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Spring Boot 4 Complete Guide learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

What a Data Fetcher Is

In Spring for GraphQL, every field in your schema is resolved by a data fetcher (the GraphQL-Java term for a resolver). When a client asks for a field, the engine invokes the fetcher bound to it.

Instead of registering raw DataFetcher beans, Spring lets you write annotated controller methods. The framework maps each method to a schema field and handles argument binding, return values, and async wrapping for you.

  • @QueryMapping resolves a field under the root Query type.
  • @MutationMapping resolves a field under the root Mutation type.
  • @SchemaMapping resolves any field (including nested object fields).

The Schema Drives Everything

Spring for GraphQL is schema-first. You declare your types and operations in an SDL file under src/main/resources/graphql/ (for example schema.graphqls), and your controller methods bind to those field names.

Consider this schema. The book and books fields live under Query, so each needs a @QueryMapping handler.

type Query {
    books: [Book!]!
    book(id: ID!): Book
}

type Mutation {
    addBook(input: AddBookInput!): Book!
}

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

input AddBookInput {
    title: String!
    pages: Int!
}

Your First @QueryMapping

A @Controller class holds your handlers. By default, Spring infers the schema field name from the method name, so books() binds to the books query.

The return value is matched against the schema's return type. Here List<Book> satisfies [Book!]!.

@Controller
public class BookController {

    private final BookService bookService;

    public BookController(BookService bookService) {
        this.bookService = bookService;
    }

    @QueryMapping
    public List<Book> books() {
        return bookService.findAll();
    }
}

Binding a Single Argument with @Argument

When a query field takes arguments, bind each one with @Argument. Spring matches the GraphQL argument name to the parameter name and coerces the value to the Java type.

For book(id: ID!), the ID scalar arrives as a String by default. Spring can also coerce it to Long if your parameter is typed that way.

@QueryMapping
public Book book(@Argument Long id) {
    return bookService.findById(id)
            .orElseThrow(() -> new BookNotFoundException(id));
}

When Argument and Parameter Names Differ

Parameter-name matching depends on debug symbols being present in the compiled class. If they are stripped, or if you simply want a different Java name, set the argument name explicitly.

  • @Argument("id") binds the schema argument id to whatever parameter you declare.
  • Compiling with the -parameters flag (the Spring Boot starter parent enables it) keeps names available, so the explicit form is often optional.
@QueryMapping
public Book book(@Argument("id") Long bookId) {
    return bookService.findById(bookId)
            .orElseThrow(() -> new BookNotFoundException(bookId));
}

Binding Input Objects to a POJO

For mutations that accept an input object, you do not bind each field separately. Instead, @Argument binds the whole GraphQL input type to a Java class. Spring populates the object field-by-field using the matching property names.

The target class just needs fields (or a constructor) matching the input's keys. A record works perfectly.

public record AddBookInput(String title, int pages) {}

@MutationMapping
public Book addBook(@Argument AddBookInput input) {
    Book created = bookService.create(input.title(), input.pages());
    return created;
}

@MutationMapping in Practice

@MutationMapping works exactly like @QueryMapping but resolves fields under the root Mutation type. Use it for operations that change state: create, update, delete.

You can mix simple scalar arguments and input objects freely. Below, an update takes both an ID and an input payload.

@MutationMapping
public Book updateBook(@Argument Long id, @Argument UpdateBookInput input) {
    Book existing = bookService.findById(id)
            .orElseThrow(() -> new BookNotFoundException(id));
    existing.setTitle(input.title());
    existing.setPages(input.pages());
    return bookService.save(existing);
}

Whole-Argument-Map Binding with @Arguments

Sometimes you want the complete set of arguments bound to a single object rather than calling @Argument repeatedly. The @Arguments (plural) annotation binds all field arguments onto one target class at once.

This is handy when a query has many filter parameters that map cleanly to a criteria object.

public record BookFilter(String titleContains, Integer minPages, Integer maxPages) {}

@QueryMapping
public List<Book> searchBooks(@Arguments BookFilter filter) {
    return bookService.search(filter);
}

Validating Bound Arguments

Spring for GraphQL integrates with Bean Validation. Annotate the controller method argument or the input record components with constraints, and add @Valid so violations are checked before your method body runs.

A failed constraint produces a GraphQL error rather than executing your business logic, keeping bad data out of the service layer.

public record AddBookInput(
        @NotBlank String title,
        @Positive int pages) {}

@MutationMapping
public Book addBook(@Argument @Valid AddBookInput input) {
    return bookService.create(input.title(), input.pages());
}

Accessing the Raw Arguments Map

For dynamic cases you can skip typed binding and inject the DataFetchingEnvironment (or an @Argument Map<String, Object>). The environment exposes the raw arguments, the selection set, and context.

Use this sparingly — typed binding with @Argument is clearer and safer. Reach for the environment only when you genuinely need engine-level details.

@QueryMapping
public Book book(DataFetchingEnvironment env) {
    Long id = Long.valueOf(env.getArgument("id").toString());
    return bookService.findById(id)
            .orElseThrow(() -> new BookNotFoundException(id));
}

A Standalone Argument-Coercion Demo

Argument binding is, at its core, coercing incoming values into Java types. The snippet below mimics that idea without any framework: it parses an ID-like string argument into a long and looks it up — exactly what @Argument Long id does under the hood.

This runs on a plain online judge to make the concept concrete.

import java.util.Map;

public class Main {
    record Book(long id, String title) {}

    public static void main(String[] args) {
        Map<Long, Book> store = Map.of(
            1L, new Book(1, "Spring in Action"),
            2L, new Book(2, "Effective Java")
        );

        String rawIdArgument = "2"; // as it would arrive from GraphQL
        long id = Long.parseLong(rawIdArgument);

        Book found = store.get(id);
        System.out.println(found != null ? found.title() : "not found");
    }
}

Quick Check

You have a mutation addBook(input: AddBookInput!): Book! where AddBookInput has fields title and pages. You want to bind the entire input object to a single Java record in one handler. What is the correct signature?

Recap

You can now wire GraphQL fields to Java handlers in Spring for GraphQL:

  • @QueryMapping and @MutationMapping bind controller methods to root Query/Mutation fields, inferring the field name from the method name.
  • @Argument binds a single GraphQL argument or an entire input object to a Java type; use the explicit name form when parameter names are unavailable.
  • @Arguments binds the full set of field arguments onto one target object.
  • @Valid plus Bean Validation constraints reject bad input before your service runs.
  • The DataFetchingEnvironment exposes raw arguments for dynamic cases, but typed binding should be your default.

Frequently asked questions

Is the “Data Fetchers and Argument Binding” lesson free?

Yes — the full text of “Data Fetchers and Argument Binding” is free to read here on the web, and the Spring Boot 4 Complete Guide course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Spring Boot 4 Complete Guide course, upgrade to CoddyKit PRO.

What will I learn in “Data Fetchers and Argument Binding”?

Implement @QueryMapping and @MutationMapping handlers with argument and input binding. You practise Spring Boot 4 Complete Guide with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Spring Boot 4 Complete Guide?

No prior experience is required. Spring Boot 4 Complete Guide on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Data Fetchers and Argument Binding” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Spring Boot 4 Complete Guide lesson?

Yes. Every Spring Boot 4 Complete Guide lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. Schema-First Design and Type Mapping
  2. Data Fetchers and Argument Binding
  3. Solving N+1 with Batch Loaders
  4. Subscriptions, Errors, and Schema Security
← Back to Spring Boot 4 Complete Guide