@Query vs NamedQuery in JPA

1. Introduction

In Java Persistence API (JPA), @Query and NamedQuery are both ways to execute database operations using JPQL (Java Persistence Query Language). @Query is an annotation used on repository methods to specify a JPQL or native SQL query. NamedQuery, on the other hand, is defined statically in the entity class and referenced by a unique name.

2. Key Points

1. @Query is used to define the query right above the method in the repository interface.

2. NamedQuery is defined at the entity level using the @NamedQuery annotation and is named for later use.

3. @Query can easily leverage Spring Data repository capabilities like pagination and sorting.

4. NamedQuery queries are statically checked at application startup, potentially catching errors early.

3. Differences

@Query NamedQuery
Defined directly on the repository method. Defined on the entity class and referenced by name.
Queries are not checked until the method is called. Queries are checked at application startup.
Can use native SQL or JPQL. Typically uses JPQL and is part of JPA standard.

4. Example

@NamedQuery(name = "User.findByName", query = "SELECT u FROM User u WHERE u.name = :name")
public class User {
    // ... entity fields, getters and setters

public interface UserRepository extends JpaRepository<User, Long> {
    // Using @Query to define a JPQL query
    @Query("SELECT u FROM User u WHERE u.email = ?1")
    User findByEmail(String email);

    // Using NamedQuery by referencing the name
    User findByName(@Param("name") String name);


// No direct output, as these annotations are part of the data access layer configuration.


1. The User entity class contains a NamedQuery with the name User.findByName, which can be used anywhere within the application by referencing its name.

2. The UserRepository interface uses @Query to define a custom find method for the email attribute. This query is directly linked to the method.

3. When findByName is called on the repository, it will use the NamedQuery defined in the User entity class.

5. When to use?

- Use @Query when you need flexibility and dynamic queries that might change at runtime, or you are heavily using Spring Data features.

- Use NamedQuery when you have a static query that won't change and you want to ensure the query is valid at application startup.