How to Use JPQL in Spring Boot: Simple Guide with Examples

In Spring Boot, use @Query annotation with JPQL inside a repository interface to write database queries using entity objects. JPQL queries use entity class names and fields instead of table names and columns, making them object-oriented and portable.

Syntax

JPQL queries are written using entity class names and their fields, not database tables. Use @Query annotation in a Spring Data JPA repository interface to define JPQL queries.

• SELECT: Choose entities or fields.
• FROM: Specify entity class.
• WHERE: Filter results with conditions.
• Parameters: Use :paramName for dynamic values.

java

public interface UserRepository extends JpaRepository<User, Long> {
    @Query("SELECT u FROM User u WHERE u.email = :email")
    User findByEmail(@Param("email") String email);
}

Example

This example shows a Spring Boot repository using JPQL to find users by their email. It demonstrates how to write a JPQL query with a parameter and how Spring injects the value.

java

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;

import java.util.List;

@Entity
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // getters and setters
}

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    @Query("SELECT u FROM User u WHERE u.email = :email")
    User findByEmail(@Param("email") String email);

    @Query("SELECT u FROM User u WHERE u.name LIKE %:namePart%")
    List<User> findByNameContains(@Param("namePart") String namePart);
}

// Usage in a service or controller
// User user = userRepository.findByEmail("[e-mail]");
// List<User> users = userRepository.findByNameContains("John");

Output

User object with email '[e-mail]' or list of users whose names contain 'John'

Common Pitfalls

Common mistakes when using JPQL in Spring Boot include:

• Using database table names instead of entity class names in queries.
• Referencing database column names instead of entity field names.
• Forgetting to use @Param annotation for query parameters.
• Writing native SQL syntax instead of JPQL syntax.

Always remember JPQL works with Java entities, not tables.

java

public interface UserRepository extends JpaRepository<User, Long> {
    // Wrong: uses table name and column
    // @Query("SELECT * FROM users WHERE email = :email")
    // User findByEmail(@Param("email") String email);

    // Right: uses entity and field names
    @Query("SELECT u FROM User u WHERE u.email = :email")
    User findByEmail(@Param("email") String email);
}

Quick Reference

JPQL Keyword	Purpose	Example
SELECT	Choose entities or fields	SELECT u FROM User u
FROM	Specify entity class	FROM User u
WHERE	Filter results	WHERE u.email = :email
ORDER BY	Sort results	ORDER BY u.name ASC
JOIN	Join related entities	JOIN u.roles r
LIKE	Pattern matching	WHERE u.name LIKE %:namePart%

Key Takeaways

Use @Query annotation in Spring Data JPA repositories to write JPQL queries.

JPQL queries use entity class names and fields, not database tables or columns.

Always annotate method parameters with @Param to bind query parameters.

Avoid mixing SQL syntax with JPQL; they have different rules.

Test queries to ensure they match your entity model and return expected results.