Lecture 284: Building Your First GraphQL Query

Today we'll take a step forward and build our first GraphQL query. Grab your mouse and a cup of coffee — let's dive in!

Building Your First GraphQL Query

GraphQL queries are a way to fetch data from the server. Unlike REST, where each endpoint returns a fixed payload, with GraphQL you describe the shape of the response yourself. For example, imagine you need a list of users but only their names and emails. GraphQL lets you request just those fields, which makes your API way more flexible.

1. Example GraphQL query

query {
  users {
    name
    email
  }
}

The server will return only that data:

{
  "data": {
    "users": [
      { "name": "Ivan", "email": "ivan@example.com" },
      { "name": "Anna", "email": "anna@example.com" }
    ]
  }
}

2. Defining a GraphQL schema

So the server knows which fields to handle, you need to create a GraphQL schema. The schema defines:

• Which queries are supported.
• What data is returned.
• What data types exist.

Example GraphQL schema

Create the file schema.graphqls in the folder src/main/resources/graphql/. In that file, declare the schema:

type Query {
    hello: String
    users: [User!]!
}

type User {
    id: ID!
    name: String!
    email: String!
}

• Query — a special type that describes all supported queries.
• hello — a simple query that returns a string.
• users — a query that returns a list of User objects.
• User — an object representing a user.

3. Adding data. Implementing Query Resolvers.

To handle GraphQL queries the server needs Query Resolvers. They describe how to fetch data for each query defined in the schema.

Implementing a Query Resolver in Spring Boot

Create a Java class to handle the queries. For example, QueryResolver:

package com.example.graphql.resolver;

import org.springframework.stereotype.Component;
import com.example.graphql.model.User;

import java.util.List;

@Component
public class QueryResolver {

    // Handler for the "hello" query
    public String hello() {
        return "Hello, GraphQL!";
    }

    // Handler for the "users" query
    public List<User> users() {
        return List.of(
            new User(1L, "Ivan", "ivan@example.com"),
            new User(2L, "Anna", "anna@example.com")
        );
    }
}

User model for data

package com.example.graphql.model;

public class User {
    private Long id;
    private String name;
    private String email;

    public User(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    // Getters
    public Long getId() {
        return id;
    }

    public String getName() {
        return name;
    }

    public String getEmail() {
        return email;
    }
}

We created two handlers (hello and users) that respond to queries from our GraphQL schema.

4. Testing the first query

Time to check how our query works! You can use tools like GraphQL Playground, Postman, or built-in IDE plugins.

Setting up GraphQL Playground

Add the following dependency to pom.xml to enable the GraphQL Playground interface:

<dependency>
    <groupId>com.graphql-java-kickstart</groupId>
    <artifactId>graphql-spring-boot-starter-playground</artifactId>
    <version>11.1.0</version>
</dependency>

Run your Spring Boot server and open:

http://localhost:8080/playground

There you can execute queries and inspect the results.

Checking the basic query

Try the hello query:

query {
  hello
}

You should get:

{
  "data": {
    "hello": "Hello, GraphQL!"
  }
}

Now try the users query:

query {
  users {
    id
    name
    email
  }
}

Result:

{
  "data": {
    "users": [
      { "id": "1", "name": "Ivan", "email": "ivan@example.com" },
      { "id": "2", "name": "Anna", "email": "anna@example.com" }
    ]
  }
}

5. Improving structure using GraphQL Resolver

To keep code better organized you can use annotations like @GraphQLQuery. This lets Spring automatically bind GraphQL queries to Java methods.

Updated Query Resolver

package com.example.graphql.resolver;

import org.springframework.stereotype.Component;
import com.example.graphql.model.User;
import com.coxautodev.graphql.tools.GraphQLQueryResolver;

import java.util.List;

@Component
public class QueryResolver implements GraphQLQueryResolver {

    public String hello() {
        return "Hello, GraphQL!";
    }

    public List<User> users() {
        return List.of(
            new User(1L, "Ivan", "ivan@example.com"),
            new User(2L, "Anna", "anna@example.com")
        );
    }
}

Now Spring automatically binds the hello and users methods to the queries described in schema.graphqls.

6. Common errors and fixes

• Error "Field 'X' in type 'Query' is undefined"
  • Make sure your schema.graphqls is defined correctly and matches your methods in QueryResolver.
• Error "No resolver found"
  • Check that your handler class is annotated with @Component and is included in the Spring context.
• Server doesn't respond to requests
  • Make sure GraphQL dependencies and configuration are added.

7. Practical use

Now you can build powerful queries for any data in your app. GraphQL queries are especially useful in client-server setups where frontend developers can request only the data they need. For example, mobile apps — where transfer time matters — benefit a lot from GraphQL.

Wrapping up:

1. You set up a GraphQL schema.
2. You created a Query Resolver to handle queries.
3. You tested your first queries.

In the next lecture we'll look at how to implement mutations (Mutations) to manage data on the server.