I just announced the new Learn Spring course, focused on the fundamentals of Spring 5 and Spring Boot 2:


1. Overview

In this tutorial, we're looking at building a query language for a REST API using Spring Data JPA and Querydsl.

In the first two articles of this series, we built the same search/filtering functionality using JPA Criteria and Spring Data JPA Specifications.

So – why a query language? Because – for any complex enough API – searching/filtering your resources by very simple fields is simply not enough. A query language is more flexible, and allows you to filter down to exactly the resources you need.

2. Querydsl Configuration

First – let's see how to configure our project to use Querydsl.

We need to add the following dependencies to pom.xml:


We also need to configure the APT – Annotation processing tool – plugin as follows:


This will generate the Q-types for our entities. 

3. The MyUser Entity

Next – let's take a look at the “MyUser” entity which we are going to use in our Search API:

public class MyUser {
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    private String firstName;
    private String lastName;
    private String email;

    private int age;

4. Custom Predicate With PathBuilder

Now – let's create a custom Predicate based on some arbitrary constraints.

We're using PathBuilder here instead of the automatically generated Q-types because we need to create paths dynamically for more abstract usage:

public class MyUserPredicate {

    private SearchCriteria criteria;

    public BooleanExpression getPredicate() {
        PathBuilder<MyUser> entityPath = new PathBuilder<>(MyUser.class, "user");

        if (isNumeric(criteria.getValue().toString())) {
            NumberPath<Integer> path = entityPath.getNumber(criteria.getKey(), Integer.class);
            int value = Integer.parseInt(criteria.getValue().toString());
            switch (criteria.getOperation()) {
                case ":":
                    return path.eq(value);
                case ">":
                    return path.goe(value);
                case "<":
                    return path.loe(value);
        else {
            StringPath path = entityPath.getString(criteria.getKey());
            if (criteria.getOperation().equalsIgnoreCase(":")) {
                return path.containsIgnoreCase(criteria.getValue().toString());
        return null;

Note how the implementation of the predicate is generically dealing with multiple types of operations. This is because the query language is by definition an open language where you can potentially filter by any field, using any supported operation.

To represent that kind of open filtering criteria, we're using a simple but quite flexible implementation – SearchCriteria:

public class SearchCriteria {
    private String key;
    private String operation;
    private Object value;

The SearchCriteria holds the details we need to represent a constraint:

  • key: the field name – for example: firstName, age, … etc
  • operation: the operation – for example: Equality, less than, … etc
  • value: the field value – for example: john, 25, … etc

5. MyUserRepository

Now – let’s take a look at our MyUserRepository.

We need our MyUserRepository to extend QuerydslPredicateExecutor so that we can use Predicates later to filter search results:

public interface MyUserRepository extends JpaRepository<MyUser, Long>, 
  QuerydslPredicateExecutor<MyUser>, QuerydslBinderCustomizer<QMyUser> {
    default public void customize(
      QuerydslBindings bindings, QMyUser root) {
          .first((SingleValueBinding<StringPath, String>) StringExpression::containsIgnoreCase);

Note that we're using here the generated Q-type for the MyUser entity, which will be named QMyUser.

6. Combine Predicates

Next– let’s take a look at combining Predicates to use multiple constraints in results filtering.

In the following example – we work with a builder – MyUserPredicatesBuilder – to combine Predicates:

public class MyUserPredicatesBuilder {
    private List<SearchCriteria> params;

    public MyUserPredicatesBuilder() {
        params = new ArrayList<>();

    public MyUserPredicatesBuilder with(
      String key, String operation, Object value) {
        params.add(new SearchCriteria(key, operation, value));
        return this;

    public BooleanExpression build() {
        if (params.size() == 0) {
            return null;

        List predicates = -> {
            MyUserPredicate predicate = new MyUserPredicate(param);
            return predicate.getPredicate();
        BooleanExpression result = Expressions.asBoolean(true).isTrue();
        for (BooleanExpression predicate : predicates) {
            result = result.and(predicate);
        return result;

7. Test the Search Queries

Next – let’s test our Search API.

We'll start by initializing the database with a few users – to have these ready and available for testing:

@ContextConfiguration(classes = { PersistenceConfig.class })
public class JPAQuerydslIntegrationTest {

    private MyUserRepository repo;

    private MyUser userJohn;
    private MyUser userTom;

    public void init() {
        userJohn = new MyUser();
        userJohn.setEmail("[email protected]");

        userTom = new MyUser();
        userTom.setEmail("[email protected]");

Next, let’s see how to find users with given last name:

public void givenLast_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder().with("lastName", ":", "Doe");

    Iterable<MyUser> results = repo.findAll(;
    assertThat(results, containsInAnyOrder(userJohn, userTom));

Now, let’s see how to find a user with given both first and last name:

public void givenFirstAndLastName_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder()
      .with("firstName", ":", "John").with("lastName", ":", "Doe");

    Iterable<MyUser> results = repo.findAll(;

    assertThat(results, contains(userJohn));
    assertThat(results, not(contains(userTom)));

Next, let’s see how to find user with given both last name and minimum age

public void givenLastAndAge_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder()
      .with("lastName", ":", "Doe").with("age", ">", "25");

    Iterable<MyUser> results = repo.findAll(;

    assertThat(results, contains(userTom));
    assertThat(results, not(contains(userJohn)));

Now, let’s see how to search for MyUser that doesn’t actually exist:

public void givenWrongFirstAndLast_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder()
      .with("firstName", ":", "Adam").with("lastName", ":", "Fox");

    Iterable<MyUser> results = repo.findAll(;
    assertThat(results, emptyIterable());

Finally – let’s see how to find a MyUser given only part of the first name – as in the following example:

public void givenPartialFirst_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder().with("firstName", ":", "jo");

    Iterable<MyUser> results = repo.findAll(;

    assertThat(results, contains(userJohn));
    assertThat(results, not(contains(userTom)));

8. UserController

Finally, let's put everything together and build the REST API.

We're defining a UserController that defines a simple method findAll() with a “search“ parameter to pass in the query string:

public class UserController {

    private MyUserRepository myUserRepository;

    @RequestMapping(method = RequestMethod.GET, value = "/myusers")
    public Iterable<MyUser> search(@RequestParam(value = "search") String search) {
        MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder();

        if (search != null) {
            Pattern pattern = Pattern.compile("(\w+?)(:|<|>)(\w+?),");
            Matcher matcher = pattern.matcher(search + ",");
            while (matcher.find()) {
        BooleanExpression exp =;
        return myUserRepository.findAll(exp);

Here is a quick test URL example:


And the response:

    "email":"[email protected]",

9. Conclusion

This third article covered the first steps of building a query language for a REST API, making good use of the Querydsl library.

The implementation is of course early on, but it can easily be evolved to support additional operations.

The full implementation of this article can be found in the GitHub project – this is a Maven-based project, so it should be easy to import and run as it is.

Next »
REST Query Language – Advanced Search Operations
« Previous
REST Query Language with Spring Data JPA Specifications
REST bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course :

Inline Feedbacks
View all comments
Comments are closed on this article!