QueryDSL Overview

QueryDSL sits at the same architectural level as Spring Data JPA—it's a universal query framework built atop various ORM implementations. Unlike traditional SQL writing, QueryDSL enables developers to write "SQL in Java code" through its fluent API. The framework excels at constructing type-safe queries, eliminating the need to work with unwieldy Object[] result sets that plague raw JPA queries. Combining Spring Data JPA with QueryDSL creates a powerful duo where Spring Data JPA handles routine CRUD operations while QueryDSL tackles complex conditional logic and projection queries.

Setting Up QueryDSL JPA

Maven Configuration

The APT (Annotation Processing Tool) plugin generates the Q-type classes that form the foundation of QueryDSL's type-safe queries. Add the following configuration to your pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>com.mysema.maven</groupId>
            <artifactId>apt-maven-plugin</artifactId>
            <version>1.1.3</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>process</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>target/generated-sources</outputDirectory>
                        <processor>com.querydsl.apt.jpa.JPAAnnotationProcessor</processor>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Add the necessary dependencies to your project:

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.16.10</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Application Properties

Configure your database connection and JPA settings:

server.port=8888
server.context-path=/
server.tomcat.uri-encoding=utf-8

spring.datasource.url=jdbc:mysql://127.0.0.1:3306/springboot_test?characterEncoding=utf8
spring.datasource.username=root
spring.datasource.password=
spring.jpa.database=mysql
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
spring.jpa.hibernate.naming.strategy=org.hibernate.cfg.ImprovedNamingStrategy

JPAQueryFactory Bean Configuration

Configure a JPAQueryFactory bean to inject into your service layer:

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    @Bean
    public JPAQueryFactory queryFactory(EntityManager entityManager) {
        return new JPAQueryFactory(entityManager);
    }
}

Entity Mapping

Define your domain entity with standard JPA annotations:

@Data
@Entity
@Table(name = "t_user")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer userId;
    private String username;
    private String password;
    private String nickName;
    private Date birthday;
    private BigDecimal sortOrder;
}

Running Maven Compilation

Execute the Maven compile goal to generate Q-type classes. After compilation, QueryDSL automatically generates a QUser class in the target/generated-sources directory:

@Generated("com.querydsl.codegen.EntitySerializer")
public class QUser extends EntityPathBase<User> {

    private static final long serialVersionUID = -646136422L;

    public static final QUser user = new QUser("user");

    public final DateTimePath<java.util.Date> birthday = createDateTime("birthday", java.util.Date.class);
    public final StringPath nickName = createString("nickName");
    public final StringPath password = createString("password");
    public final NumberPath<java.math.BigDecimal> sortOrder = createNumber("sortOrder", java.math.BigDecimal.class);
    public final NumberPath<Integer> userId = createNumber("userId", Integer.class);
    public final StringPath username = createString("username");

    public QUser(String variable) {
        super(User.class, forVariable(variable));
    }

    public QUser(Path<? extends User> path) {
        super(path.getType(), path.getMetadata());
    }

    public QUser(PathMetadata metadata) {
        super(User.class, metadata);
    }
}

These Q-type classes serve as the entry point for all QueryDSL operations, enabling compile-time type checking.

QueryDSL Usage Patterns

Repository Setup

Extend QueryDslPredicateExecutor to combine Spring Data JPA with QueryDSL capabilities:

public interface UserRepository extends JpaRepository<User, Integer>, QueryDslPredicateExecutor<User> {
}

Create a DTO for partial field projection:

@Data
@Builder
public class UserSummary {
    private String userId;
    private String username;
    private String nickname;
    private String birthDate;
}

Service Layer Implementation

@Service
public class UserManagementService {

    @Autowired
    private UserRepository userRepository;

    @Autowired
    private JPAQueryFactory queryFactory;

    /**
     * Authentication query using composite conditions
     */
    public User authenticate(String username, String password) {
        QUser u = QUser.user;
        return queryFactory
                .selectFrom(u)
                .where(
                        u.username.eq(username),
                        u.password.eq(password)
                )
                .fetchOne();
    }

    /**
     * Retrieve all records with custom ordering
     */
    public List<User> getAllUsersSorted() {
        QUser u = QUser.user;
        return queryFactory
                .selectFrom(u)
                .orderBy(u.sortOrder.asc())
                .fetch();
    }

    /**
     * Paginated retrieval with sorting
     */
    public QueryResults<User> getPaginatedUsers(Pageable pageable) {
        QUser u = QUser.user;
        return queryFactory
                .selectFrom(u)
                .orderBy(u.sortOrder.asc())
                .offset(pageable.getOffset())
                .limit(pageable.getPageSize())
                .fetchResults();
    }

    /**
     * Date range filtering
     */
    public List<User> getUsersByDateRange(Date startDate, Date endDate) {
        QUser u = QUser.user;
        return queryFactory
                .selectFrom(u)
                .where(u.birthday.between(startDate, endDate))
                .fetch();
    }

    /**
     * Projection query with stream-based transformation
     */
    public List<UserSummary> getUserSummaries(Pageable pageable) {
        QUser u = QUser.user;
        return queryFactory
                .select(u.username, u.userId, u.nickName, u.birthday)
                .from(u)
                .offset(pageable.getOffset())
                .limit(pageable.getPageSize())
                .fetch()
                .stream()
                .map(tuple -> UserSummary.builder()
                        .username(tuple.get(u.username))
                        .nickname(tuple.get(u.nickName))
                        .userId(tuple.get(u.userId).toString())
                        .birthDate(new SimpleDateFormat("yyyy-MM-dd").format(tuple.get(u.birthday)))
                        .build())
                .collect(Collectors.toList());
    }

    /**
     * Spring Data JPA integration with QueryDSL predicates
     */
    public List<User> searchByNicknameAndUsername(String nickname, String username) {
        QUser u = QUser.user;
        return (List<User>) userRepository.findAll(
                u.nickName.eq(nickname).and(u.username.eq(username)),
                u.sortOrder.asc()
        );
    }

    /**
     * Count matching records with pattern matching
     */
    public long countUsersWithNicknameLike(String pattern) {
        QUser u = QUser.user;
        return userRepository.count(u.nickName.like("%" + pattern + "%"));
    }

    /**
     * Dynamic conditional query with optional parameters
     */
    public Page<User> advancedSearch(
            Pageable pageable,
            String username,
            String password,
            String nickName,
            Date birthday,
            BigDecimal sortOrder) {

        QUser u = QUser.user;
        Predicate conditions = u.isNotNull().or(u.isNull());

        conditions = username == null ? conditions : ExpressionUtils.and(conditions, u.username.eq(username));
        conditions = password == null ? conditions : ExpressionUtils.and(conditions, u.password.eq(password));
        conditions = nickName == null ? conditions : ExpressionUtils.and(conditions, u.nickName.eq(nickName));
        conditions = birthday == null ? conditions : ExpressionUtils.and(conditions, u.birthday.eq(birthday));
        conditions = sortOrder == null ? conditions : ExpressionUtils.and(conditions, u.sortOrder.eq(sortOrder));

        return userRepository.findAll(conditions, pageable);
    }

    /**
     * Grouping with dynamic conditions and HAVING clause
     */
    public List<User> groupedSearch(
            String username,
            String password,
            String nickName,
            Date birthday,
            BigDecimal sortOrder) {

        QUser u = QUser.user;
        Predicate conditions = u.isNotNull().or(u.isNull());

        conditions = username == null ? conditions : ExpressionUtils.and(conditions, u.username.eq(username));
        conditions = password == null ? conditions : ExpressionUtils.and(conditions, u.password.eq(password));
        conditions = nickName == null ? conditions : ExpressionUtils.and(conditions, u.nickName.eq(nickName));
        conditions = birthday == null ? conditions : ExpressionUtils.and(conditions, u.birthday.eq(birthday));
        conditions = sortOrder == null ? conditions : ExpressionUtils.and(conditions, u.sortOrder.eq(sortOrder));

        return queryFactory
                .selectFrom(u)
                .where(conditions)
                .orderBy(u.userId.asc())
                .groupBy(u.sortOrder)
                .having(u.sortOrder.longValue().max().gt(7))
                .fetch();
    }
}

Key Implementation Details

a) Authentication Query: Uses selectFrom() as shorthand for select().from() with multiple where() conditions passed as varargs. The eq() method returns BooleanExpression wich implements Predicate.

b) Ordered Results: The fluent API mirrors SQL semantics directly—orderBy() accepts OrderSpecifier instances generated from field paths.

c) Pagination: offset() and limit() handle pagination while fetchResults() returns both the result list and total count in a QueryResults wrapper.

d) Date Range: The between() method provides inclusive range filtering on date fields.

e) Projection with Streams: When selecting specific columns instead of the full entity, the result is a List<Tuple>. The Tuple interface functions as a type-safe Map, retrievable via tuple.get(QEntity.field). Stream operations enable inline type conversion during the mapping phase.

f) Repository Integration: QueryDslPredicateExecutor provides methods accepting Predicate parameters, enabling seamless integration with Spring Data JPA's repository pattern while leveraging QueryDSL's fluent condition building.

g) Dynamic Query Construction: The pattern u.isNotNull().or(u.isNull()) creates a neutral starting predicate similar to WHERE 1=1. Each subsequent condition uses ExpressionUtils.and() to chain predicates, maintaining type safety throughout the construction process.

Multi-Table Queries

Define a related entity for one-to-many relationships:

@Data
@Entity
@Table(name = "t_department")
public class Department {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer deptId;
    private String deptName;
    private Date createdAt;
}

Update the User entity with the relationship:

@Data
@Entity
@Table(name = "t_user")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer userId;
    private String username;
    private String password;
    private String nickName;
    private Date birthday;
    private BigDecimal sortOrder;

    @ManyToOne(cascade = CascadeType.MERGE, fetch = FetchType.EAGER)
    @JoinColumn(name = "department_id")
    private Department department;
}

Create a composite DTO for joined results:

@Data
@Builder
public class UserWithDepartmentDTO {
    private String username;
    private String nickname;
    private String birthDate;
    private String departmentName;
    private String departmentCreatedAt;
}

Implement the joined query:

/**
 * Fetch user details along with department information
 */
public List<UserWithDepartmentDTO> getUsersWithDepartments(int departmentId) {
    QUser user = QUser.user;
    QDepartment dept = QDepartment.department;

    return queryFactory
            .select(user.username, user.nickName, user.birthday, dept.deptName, dept.createdAt)
            .from(user)
            .join(user.department, dept)
            .where(dept.deptId.eq(departmentId))
            .fetch()
            .stream()
            .map(tuple -> UserWithDepartmentDTO.builder()
                    .username(tuple.get(user.username))
                    .nickname(tuple.get(user.nickName))
                    .birthDate(new SimpleDateFormat("yyyy-MM-dd").format(tuple.get(user.birthday)))
                    .departmentName(tuple.get(dept.deptName))
                    .departmentCreatedAt(new SimpleDateFormat("yyyy-MM-dd").format(tuple.get(dept.createdAt)))
                    .build())
            .collect(Collectors.toList());
}

Foreign Key Approach

When entities only contain foreign key columns without relationship annotations:

@Data
@Entity
@Table(name = "t_user")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Integer userId;
    private String username;
    private String password;
    private String nickName;
    private Date birthday;
    private BigDecimal sortOrder;
    private Integer departmentId;
}

Modify the query to handle explicit joins:

public List<UserWithDepartmentDTO> getUsersWithDepartmentsByFK(int departmentId) {
    QUser user = QUser.user;
    QDepartment dept = QDepartment.department;

    return queryFactory
            .select(user.username, user.nickName, user.birthday, dept.deptName, dept.createdAt)
            .from(user, dept)
            .where(user.departmentId.eq(dept.deptId).and(dept.deptId.eq(departmentId)))
            .fetch()
            .stream()
            .map(tuple -> UserWithDepartmentDTO.builder()
                    .username(tuple.get(user.username))
                    .nickname(tuple.get(user.nickName))
                    .birthDate(new SimpleDateFormat("yyyy-MM-dd").format(tuple.get(user.birthday)))
                    .departmentName(tuple.get(dept.deptName))
                    .departmentCreatedAt(new SimpleDateFormat("yyyy-MM-dd").format(tuple.get(dept.createdAt)))
                    .build())
            .collect(Collectors.toList());
}

This approach mimics SQL's implicit joins by specifying both entities in the from() clause and establishing the relationship through where() conditions.

Practical Considerations

Spring Data JPA handles straightforward CRUD operations effectively, but QueryDSL excels when facing complex conditional logic, dynamic query construction, and projection queries that transform database results into specific DTO structures. The integration between these two technologies provides flexibility—use Spring Data JPA's repository abstraction for basic operations and switch to QueryDSL when the query complexity increases.

For scenarios involving dynamic WHERE clauses, conditional JOINs, GROUP BY with HAVING, or field-level projections, QueryDSL's fluent API significant reduces boilerplate compared to manual JPQL or native SQL construction. The type safety provided by generated Q-classes catches errors at compile time rather than runtime, improving code reliability during maintenance.