@Query

---

🔍 @Query

정의

@Query는 Spring Data JPA에서 Repository 메서드에 직접 쿼리를 작성하기 위한 애너테이션이다. JPQL 또는 네이티브 SQL을 사용할 수 있다.

메서드 이름만으로 표현하기 어려운 조회 조건이 있을 때 사용한다.

🧩 역할

• Repository 메서드에 직접 쿼리를 정의한다
• 복잡한 조건 조회를 쉽게 작성한다
• JPQL과 네이티브 SQL을 모두 지원한다
• 메서드 이름 파생 쿼리보다 더 세밀한 조건을 작성할 수 있다

🛠 사용법

JPQL 예시

import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.CrudRepository;
import java.util.List;

public interface UserRepository extends CrudRepository<User, Long> {

    @Query("SELECT u FROM User u WHERE u.status = 'ACTIVE'")
    List<User> findActiveUsers();
}

네이티브 쿼리 예시

@Query(value = "SELECT * FROM user WHERE status = 'ACTIVE'", nativeQuery = true)
List<User> findActiveUsersNative();

파라미터 바인딩 예시

@Query("SELECT u FROM User u WHERE u.email = :email")
User findByEmail(String email);

⚠️ 주의사항

• JPQL은 엔티티명과 엔티티 필드를 기준으로 작성해야 한다.
• 네이티브 쿼리를 사용할 때는 DB 문법에 종속될 수 있다.
• 조회가 아닌 UPDATE, DELETE에는 보통 @Modifying이 함께 필요하다.
• 파라미터 바인딩은 문자열 결합보다 : 형태를 사용하는 것이 안전하다.

📌 정리

• @Query는 Repository 메서드에 직접 쿼리를 적는 애너테이션이다.
• JPQL과 네이티브 SQL을 모두 지원한다.
• 복잡한 조회나 특수한 조건이 필요할 때 유용하다.

---

연결문서

• JPQL
• @Modifying