How to Use QueryDSL in Spring Boot 3: A Complete Guide to Type-Safe Queries [2025 Update]

QueryDSL is a powerful framework for building type-safe, dynamic queries in Java applications. With Spring Boot 3 adopting Jakarta EE and deprecating javax.persistence, integrating QueryDSL requires updated configurations to avoid pitfalls like java.lang.NoClassDefFoundError. This guide walks through setting up QueryDSL in Spring Boot 3 and building dynamic query.

Why Use QueryDSL in Spring Boot?

1. Type Safety: Compile-time validation eliminates runtime errors caused by typos or incorrect field references.
2. Fluent API: Simplify complex queries with an intuitive, SQL-like syntax.
3. Dynamic Filtering: Build queries programmatically based on runtime conditions (e.g., user input).

Step 1: Create Entity Class

We will create Product entity.

package com.codersathi.springboot3querydsl.entity;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import lombok.Data;

@Entity
@Data
public class Product {
	@Id
	private Long id;

	private String name;

	private String description;

	private Double price;

	private String category;
}

Step 2: Create Repository

In this step, we will create a repository for Product entity by extending QueryDslPredicateExecutor interface along with JpaRepository.

package com.codersathi.springboot3querydsl.repository;

import com.codersathi.springboot3querydsl.entity.Product;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.querydsl.QuerydslPredicateExecutor;

public interface ProductRepository extends JpaRepository<Product, Long>,
		QuerydslPredicateExecutor<Product> {
}

Step 3: Add Dependencies

Include these in pom.xml:

<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-jpa</artifactId>
    <version>5.0.0</version>
    <classifier>jakarta</classifier> <!-- Required for Spring Boot 3 -->
</dependency>
<dependency>
    <groupId>com.querydsl</groupId>
    <artifactId>querydsl-apt</artifactId>
    <version>5.0.0</version>
    <classifier>jakarta</classifier>
    <scope>provided</scope>
</dependency>

Step 4: Generate Q-Classes

QueryDSL generates Q-classes (e.g., QProduct) from JPA entities. For Maven, add the apt-maven-plugin:

<plugin>
    <groupId>com.mysema.maven</groupId>
    <artifactId>apt-maven-plugin</artifactId>
    <version>1.1.3</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>

Run mvn clean compile to generate Q-classes.

Step 4: Write Type-Safe Queries

Example 1: Basic Filtering

public List<Product> getProductsByCategory(String category) {
	QProduct product = QProduct.product;

	BooleanExpression expression = product.category.eq(category);
		
	return (List<Product>) productRepository.findAll(expression);
}

This query returns the product matching the given category. This is equivalent to folloowing query:

SELECT * FROM product where category =:category;

Example 2: Dynamic Conditions

Use BooleanBuilder for flexible filtering:

public List<Product> getAllProducts(Double minPrice, Double maxPrice) {
	BooleanBuilder builder = new BooleanBuilder();
	QProduct product = QProduct.product;
	if (minPrice != null) {
		builder.and(product.price.goe(minPrice)); // >=
	}
	if (maxPrice != null) {
		builder.and(product.price.loe(maxPrice)); // <=
	}

	return (List<Product>) productRepository.findAll(builder);
}

This is just the example code. You can adjust as per your requirement.

And the equivalent to sql is:

SELECT * FROM Product 
WHERE (price >= :minPrice OR :minPrice IS null) 
AND (price <= :maxPrice OR :maxPrice IS null);

Example 3: QueryDSL with Pagination

We can use QueryDSL with Pagination. See the example below:

public PaginatedResponse getAllProducts(Double minPrice, Double maxPrice, Pageable pageable) {
	BooleanBuilder builder = new BooleanBuilder();
	QProduct product = QProduct.product;
	if (minPrice != null) {
		builder.and(product.price.goe(minPrice)); // >=
	}
	if (maxPrice != null) {
		builder.and(product.price.loe(maxPrice)); // <=
	}

	Page<Product> pagedProduct = productRepository.findAll(builder, pageable);

	long totalProduct = pagedProduct.getTotalElements(); // total product count
	List<Product> productList = pagedProduct.getContent(); // only paginated list

       // return your response
}

If you want to know how Pageable works then you can read our guide on how to use pagination and sorting in spring boot.

Troubleshooting Common Issues

• Q-Classes Not Generated: Ensure the apt plugin is correctly configured and the output directory is marked as a source root in your IDE.
• Jakarta EE Compatibility: Replace javax.persistence dependencies with jakarta-classified ones.

Conclusion

QueryDSL in Spring Boot streamlines query building with type safety, dynamic conditions, and pagination support, addressing common JPA limitations. By following this guide, you can avoid configuration pitfalls, optimize database interactions, and write maintainable code. For advanced use cases like projections and subqueries, explore our guide Spring Data JPA Projection and QueryDSL projections.