## 📘 Spring Data JPA | @Query 어노테이션과 JPQL 정리

📘 Spring Data JPA | @Query 어노테이션과 JPQL 정리

Spring Data JPA를 사용하면 @Query 어노테이션을 통해 직접 JPQL(JPA Query Language)을 작성할 수 있습니다. SQL과 비슷해 보이지만 엔티티 중심으로 동작하기 때문에 몇 가지 중요한 차이점과 주의할 점이 있습니다. 이 글에서는 @Query를 사용하는 방법과 JPQL의 핵심 개념들을 간단하고 명확하게 설명합니다.

---

☑️ JPQL과 SQL의 차이: from 절의 대상

• SQL: 테이블을 기준으로 쿼리를 작성 → from board
• JPQL: 엔티티를 기준으로 쿼리를 작성 → from Board b
  ✅ Board는 자바 클래스 이름이므로 대문자를 사용해야 하며, 알리아스(b)를 반드시 붙여 사용하는 것이 일반적입니다.

@Query("select b from Board b")
List<Board> findAllBoards();

➡️ select * from board 와 비슷하지만, 엔티티 기준이라는 점이 다릅니다.

---

🧲 전체가 아닌 필드만 가져올 때

@Query("select b.seq, b.title from Board b where b.title like %?1%")
List<Object[]> findSeqAndTitle(String keyword);

• b.seq, b.title처럼 일부 필드만 선택하면 반환 타입은 List<Object[]>가 됩니다.
• Object[]로 받는 이유: b.seq는 Long, b.title은 String 등 리턴 타입이 섞여 있기 때문입니다.
• 이는 SQL의 select seq, title from board와 유사하지만, JPQL은 클래스 기반으로 이해해야 합니다.

📌 Tip: 가장 간단한 방법은 엔티티 전체(Board)를 받는 것입니다. 리턴 타입이 명확하고 코드도 깔끔해지기 때문에 JPQL의 큰 장점 중 하나로 꼽힙니다.

---

🔄 위치 기반 vs 이름 기반 파라미터

✅ 위치 기반 파라미터 (기본 방식)

@Query("select b from Board b where b.title like %?1%")
List<Board> searchByTitle(String keyword);

• ?1은 첫 번째 파라미터를 의미
• 파라미터 순서가 바뀌면 쿼리도 함께 바꿔야 하므로 유지보수에 다소 불리

✅ 이름 기반 파라미터 (가독성 ↑)

@Query("select b from Board b where b.title like %:title%")
List<Board> searchByTitle(@Param("title") String keyword);

• :title → 변수명을 기준으로 매핑
• 파라미터 순서와 무관하게 작동하며, 이름이 같으면 @Param 생략도 가능:

  @Query("select b from Board b where b.title like %:keyword%")
  List<Board> searchByTitle(String keyword); // keyword 이름이 같으면 @Param 생략 가능

---

💡 핵심 요약

항목	JPQL	SQL
대상	엔티티 클래스	DB 테이블
FROM 절	from Board b	from board
SELECT 절	b 또는 b.seq, b.title	*, seq, title
리턴 타입	List<Board>, List<Object[]>	ResultSet
파라미터	위치 기반 ?1, 이름 기반 :paramName	?, :paramName

---

📦 예제: 필드 일부만 선택한 JPQL

@Query("select b.seq, b.title, b.writer, b.createDate "
     + "from Board b "
     + "where b.title like %?1% "
     + "order by b.seq desc")
List<Object[]> queryAnnotationTest2(String searchKeyword);

📝 설명:

• select b.seq, b.title ... → 일부 필드만 선택
• 리턴 타입이 Object[]인 이유: 모든 필드의 타입이 다르기 때문
• 타입을 명확히 정의한 DTO로 받는 방법도 가능하지만, 가장 간단한 형태는 Object[]

---

🧩 참고 팁

• @Query는 JPQL 기반입니다. 네이티브 SQL을 쓰고 싶다면 nativeQuery = true 옵션을 사용하세요.
• Page<T>와 함께 페이징 쿼리도 작성할 수 있습니다.
• JPA는 타입 안정성과 구조적인 쿼리 구성을 지원하기 때문에, @Query를 잘 활용하면 유지보수성과 성능을 함께 잡을 수 있습니다.

---

---

1️⃣ like %?1%에서 퍼센트 %는 뭐야?

이건 SQL에서 사용하는 패턴 매칭 기호예요.

기호	의미
%	"모든 문자열"을 뜻해요 (0글자 이상)

---

예시로 설명할게요:

@Query("select b from Board b where b.title like %?1%")

위 쿼리에서 ?1은 첫 번째 파라미터고, %는 다음과 같은 의미가 있어요:

• %?1% → 파라미터 값을 포함하는 문자열

• 예: 파라미터로 "제목"을 넘기면
  → like '%제목%'가 되어
  → "테스트 제목1" "공지 제목입니다" 같은 것들이 검색돼요.

  

---

2️⃣ @Param 생략 가능한 조건: 파라미터 이름이 같으면 생략 가능

예를 들어 아래 코드:

@Query("select b from Board b where b.title like %:keyword%")
List<Board> searchByTitle(@Param("keyword") String keyword);

여기서:

• :keyword ← JPQL 쿼리 안에서 쓰는 이름
• @Param("keyword") ← 자바 코드에서 이 이름을 바인딩

이때 자바의 파라미터 이름(keyword)이 JPQL 안의 이름(:keyword)과 완전히 같다면 @Param("keyword")를 생략해도 OK예요!

---

✅ 생략 가능한 예:

@Query("select b from Board b where b.title like %:keyword%")
List<Board> searchByTitle(String keyword); // 생략 가능: 변수명이 같음

---

❌ 생략 불가능한 예 (이름이 다름):

@Query("select b from Board b where b.title like %:keyword%")
List<Board> searchByTitle(String title); // 변수명(title)과 파라미터(keyword)가 다르니까 생략 불가!

이 경우에는 꼭 이렇게 써야 해요:

List<Board> searchByTitle(@Param("keyword") String title);

---

🔚 요약 정리

구분	설명
%	SQL에서 "아무 글자"를 의미함. like %제목% → 제목이 포함된 모든 문자열 검색
@Param 생략	메서드 파라미터 이름과 JPQL 파라미터 이름이 같을 때만 생략 가능

---

쿼리문 띄어쓰기 주의하기.

how to use multiple like conditions with @Query.

Let’s clarify step by step. 😄

---

🔸 You wrote:

List<Board> boardList = boardRepo.queryAnnotationTest1("제목10", "333");

You expect this to run a JPQL query like:

select b from Board b 
where b.title like %?1% and ... like %?2%

But you can’t write like %?1% directly like that.

---

✅ Correct way to write JPQL with multiple like %...% patterns:

@Query("select b from Board b where b.title like %?1% and b.writer like %?2%")
List<Board> queryAnnotationTest1(String titleKeyword, String writerKeyword);

✅ Yes! This is the correct way to use two like filters with position-based parameters (?1, ?2).

---

💡 BUT: Even better → use string concatenation in JPQL

Spring Data JPA actually doesn’t allow %?1% directly in all cases.
Instead, you should write it like this:

@Query("select b from Board b where b.title like concat('%', ?1, '%') and b.writer like concat('%', ?2, '%')")
List<Board> queryAnnotationTest1(String titleKeyword, String writerKeyword);

🔎 What’s happening here?

• concat('%', ?1, '%') → dynamically builds '%제목10%'
• Safer and cleaner!

---

🔁 이름 기반 버전 (optional):

@Query("select b from Board b where b.title like concat('%', :title, '%') and b.writer like concat('%', :writer, '%')")
List<Board> queryAnnotationTest1(@Param("title") String titleKeyword, @Param("writer") String writerKeyword);

---

✅ Summary:

Your case	What to write
Want to filter title and writer both with %keyword%	Use concat('%', ?1, '%') for position-based or :title with @Param for name-based