[Spring]JPQL과 네이티브 쿼리 쉽게 배우기 – SQL 없이 JPA로 데이터 가져오기!

🧠 JPQL과 네이티브 쿼리 쉽게 배우기 – SQL 없이 JPA로 데이터 가져오기!

안녕하세요!
오늘은 Spring Data JPA에서 SQL 없이도 데이터를 조회하는 두 가지 방법,
바로 JPQL과 **네이티브 쿼리(Native Query)**에 대해 알아볼 거예요.
초등학생도 이해할 수 있도록 쉽고 재미있게 풀어볼게요!

---

📌 1. JPQL이란?

🗣 JPQL = Java Persistence Query Language

JPQL은 테이블이 아니라 "객체(Entity)"를 기준으로 쿼리를 작성해요.
마치 “학생(Student) 중에서 이름이 민수인 애를 찾아줘”라고 말하는 느낌이죠!

 

예:

-- SQL 
SELECT * FROM board WHERE title = '제목1'; 

-- JPQL 
SELECT b FROM Board b WHERE b.title = '제목1';

• Board는 테이블이 아니라 자바 클래스
• b는 별명(alias)

 

잠깐! 쿼리를 만드는 다른 방법들도 있나요?

네! Spring Data JPA는 사실 여러 가지 방법으로 쿼리를 만들 수 있게 도와줘요.

• 자동 생성:
  • 쿼리 메서드 (Query Methods): 메서드 이름을 특정 규칙에 맞게 만들면 (예: findByTitle(String title)), Spring Data JPA가 알아서 쿼리를 뚝딱 만들어줘요! (가장 간편한 방법 중 하나죠!)
  • JPA Criteria (JPA 표준): 자바 코드로 쿼리를 조립하는 방식이에요. (좀 더 복잡할 수 있어요)
  • Querydsl (오픈 소스): 역시 자바 코드로 안전하고 쉽게 쿼리를 만들게 도와주는 인기 라이브러리예요.
• 수동 생성 (오늘의 주인공!):
  • EntityManager의 createQuery() 사용: JPA 표준 방법으로, 직접 JPQL 문자열을 전달해서 셔리를 만들어요.
  • @Query 어노테이션 사용: Spring Data JPA의 편리한 기능! 인터페이스 메서드 위에 @Query를 붙이고 JPQL이나 SQL을 직접 써넣을 수 있어요.

오늘은 이 중에서 수동으로 우리만의 JPQL과 네이티브 쿼리를 작성하는 방법에 집중해 볼게요!

---

🛠 2. JPQL 작성하는 방법

JPQL을 사용하는 방법은 2가지가 있어요!

✅ 방법 1: @Query 애너테이션 사용

우리가 만든 Repository 인터페이스의 메서드 위에 @Query 라는 마법 딱지를 붙이고, 그 안에 JPQL 레시피를 적어 넣는 거예요. 마치 레시피북의 특정 요리법 위에 "특별 지시사항: 이대로 요리할 것!" 이라고 메모를 붙이는 것과 같죠.

 

// BoardRepository.java 예시
public interface BoardRepository extends CrudRepository<Board, Long> {
    @Query("SELECT b FROM Board b") // <<-- 바로 이 부분!
    List<Board> findAllBoard(); // 메서드 이름은 자유롭게 지어도 괜찮아요!
}

• @Query("여기에_JPQL_레시피_작성") 형태로 사용해요.
• 중요! @Query를 사용하면, Spring Data JPA가 이 JPQL을 실행해주기 때문에 메서드 이름(findAllBoard())은 굳이 JPA의 쿼리 메서드 생성 규칙(예: findBy...)을 따르지 않아도 괜찮아요! 그냥 우리가 알아보기 쉬운 이름으로 지으면 된답니다.
• 여기서 Board는 데이터베이스 테이블 이름이 아니라, 우리가 만든 Board 엔티티 클래스 이름이고, b는 Board 엔티티를 가리키는 별명(alias) 같은 거예요. JPQL은 대소문자를 구분하는 부분(엔티티 이름, 필드 이름 등)이 있으니 주의해야 해요!

---

✅ 방법 2: EntityManager.createQuery() 사용

 

마치 데이터 관리자(EntityManager)에게 정식으로 "이런이런 조건에 맞는 데이터를 찾아주세요" 라고 상세한 요청서를 작성해서 보내는 것과 같아요.

// BoardRepositoryTest3.java 예시 중
// ...
String query = "SELECT b FROM Board b"; // Board 엔티티에서 모든 b를 선택한다!
TypedQuery<Board> tQuery = em.createQuery(query, Board.class); // EntityManager(em)에게 요청서 전달!
List<Board> list = tQuery.getResultList(); // 결과 목록 받기!
// ...

• em.createQuery(JPQL문자열, 반환될_엔티티_타입.class) 형태로 사용해요.
• JPA의 표준 방법이라 어떤 JPA 구현체(예: Hibernate)를 쓰든 동일하게 동작하지만, Spring Data JPA Repository 인터페이스에서는 보통 아래 방법을 더 많이 써요.

---

🎯 3. JPQL 매개변수 지정하기

쿼리에 값을 넣는 방법은 2가지예요!

방법예시 코드

 

순서대로 ?1	b.title = ?1 AND b.writer = ?2
이름으로 :변수명	b.title = :title AND b.writer = :writer

 

@Query("SELECT b FROM Board b WHERE b.title=?1 AND b.writer=?2")
List<Board> findByTitleAndWriter2(String title, String writer);

@Query("SELECT b FROM Board b WHERE b.title=:title AND b.writer=:writer")
List<Board> findByTitleAndWriter3(String title, String writer);

---

🏁 4. 네이티브 쿼리(Native Query)란?

JPQL이 아닌, 진짜 SQL을 그대로 쓰고 싶을 때는 네이티브 쿼리를 써요!

• 네이티브 쿼리: 데이터베이스 종류에 따라 조금씩 다를 수 있는, 그 데이터베이스만의 순수한 SQL을 직접 사용하는 거예요.
• 언제 사용할까요?
  • JPQL로 표현하기 어려운 매우 복잡한 쿼리
  • 특정 데이터베이스만의 고유 기능 사용 시
  • 통계 쿼리나 대량 데이터 처리 등에서 SQL 직접 튜닝이 필요할 때
• 어떻게 사용할까요? @Query 어노테이션에 nativeQuery = true 옵션을 추가하면 돼요!

 

// BoardRepository.java 예시
@Query(value = "SELECT * FROM BOARD", nativeQuery = true) // nativeQuery = true 필수!
List<Board> findAllBoardSQL();​

 

• value 속성에는 실제 SQL 문장을 써주고, nativeQuery = true를 꼭 붙여줘야 "이건 JPQL 아니고 진짜 SQL이야!" 라고 Spring Data JPA에게 알려줄 수 있어요.
• 주의! 네이티브 쿼리는 실제 데이터베이스 테이블 이름과 컬럼 이름을 사용해야 해요. (예: Board 엔티티가 BOARD_TABLE 테이블에 저장된다면, SQL은 SELECT * FROM BOARD_TABLE이 되어야겠죠. 예제에서는 엔티티 이름과 테이블 이름이 Board로 같은 경우예요.)

---

✅ 일부 컬럼만 조회할 땐?

 

@Query(value = "SELECT TITLE, WRITER FROM BOARD", nativeQuery = true)
List<Object[]> findAllBoardSQL2();

• Board 전체가 아니라 제목과 글쓴이만 조회해요
• 반환 타입은 List<Object[]> (배열 형태)

❓ 그런데 왜 Object[]로 받아야 할까요?

• SQL로 SELECT TITLE, WRITER처럼 여러 컬럼을 골라서 조회하면,
• JPA는 이 결과를 하나의 클래스(Board)로 만들 수 없어요. 왜냐하면 content, viewCnt 같은 다른 정보가 없기 때문이죠!

그래서 JPA는 이렇게 처리해요:

조회 결과저장 형태

전체 엔티티	List<Board>
일부 컬럼	List<Object[]>

 

예를 들어,
["title1", "writer1"] 이런 식으로 배열(Object[])에 담아서 반환해요.

---

🔁 만약 컬럼이 1개뿐이라면?

@Query(value = "SELECT WRITER FROM BOARD", nativeQuery = true) List<Object> findAllWriters();

• 이처럼 하나의 컬럼만 조회하면 Object[] 대신 **그냥 Object**로 받아도 돼요!
• 이유는 간단해요: 배열이 필요 없으니까요!

---

📦 정리 요약

조회 방식반환 타입이유

SELECT *	List<Board>	모든 속성을 가져오므로 Board에 자동 매핑 가능
SELECT TITLE, WRITER	List<Object[]>	일부 컬럼만 가져오기 때문에 배열 형태로 받음
SELECT WRITER	List<Object>	컬럼이 하나일 경우 배열이 필요 없음

 

이처럼 반환 타입은 JPQL 또는 SQL에서 어떤 컬럼을 조회하느냐에 따라 결정돼요.
혼동을 피하려면 쿼리를 작성할 때 어떤 데이터를 받아야 하는지도 함께 생각해야 한답니다 😊

---

📄 5. 페이징과 정렬도 가능해요!

✔ 페이징 (Pageable)

 

@Query("SELECT b FROM Board b")
Page<Board> findAllWithPaging(Pageable pageable);

---

✔ 정렬 (Sort)

 

Sort sort = Sort.by(Sort.Direction.DESC, "inDate");
List<Board> list = boardRepository.findAll(sort);

• DESC = 내림차순
• ASC = 오름차순

---

실전 코드 엿보기 (테스트 코드 설명) 🧪

이제 오늘 배운 내용들이 실제 테스트 코드(BoardRepositoryTest3.java)에서 어떻게 사용되는지 살펴볼게요!

 

// BoardRepositoryTest3.java
@SpringBootTest // 스프링 부트 환경에서 테스트!
@TestMethodOrder(MethodOrderer.OrderAnnotation.class) // @Order 순서대로 테스트 실행!
class BoardRepositoryTest3 {
    @Autowired // EntityManager 와 BoardRepository 를 스프링이 준비해줘!
    public EntityManager em;
    @Autowired
    private BoardRepository boardRepository;

    @BeforeEach // 각 테스트(@Test) 실행 전에 항상 먼저 실행되는 부분!
    public void testData() {
        // 테스트를 위해 100개의 게시글 데이터를 미리 만들어둬요.
        for (int i = 0; i < 100; i++) {
            Board board = new Board();
            board.setBno((long)i);
            board.setTitle("title" + i);
            board.setContent("content" + i);
            board.setWriter("writer" + (i % 5)); // 작성자는 0~4번이 반복돼요.
            board.setViewCnt((long)(Math.random()*100));
            board.setInDate(new Date());
            board.setUpDate(new Date());
            boardRepository.save(board); // CrudRepository의 save로 저장!
        }
    }

    // 1. @Query로 JPQL 작성 테스트 (모든 게시글 조회)
    @Test
    @DisplayName("@Query로 JPQL작성 테스트")
    public void queryAnnoTest() {
        List<Board> list = boardRepository.findAllBoard(); // 우리가 @Query로 만든 메서드 호출!
        assertTrue(list.size() == 100); // 100개 잘 찾아왔는지 확인!
    }

    // 2. @Query로 JPQL 작성 테스트 - 매개변수 순서 기반
    @Test
    @DisplayName("@Query로 JPQL작성 테스트 - 매개변수 순서")
    public void queryAnnoTest2() {
        // 제목이 "title1"이고 작성자가 "writer1"인 게시글 찾기! (?1, ?2 방식)
        List<Board> list = boardRepository.findByTitleAndWriter2("title1", "writer1");
        assertTrue(list.size() == 1); // 1개 찾아져야 해요!
    }

    // 3. @Query로 JPQL 작성 테스트 - 매개변수 이름 기반
    @Test
    @DisplayName("@Query로 JPQL작성 테스트 - 매개변수 이름")
    public void queryAnnoTest3() {
        // 제목이 "title1"이고 작성자가 "writer1"인 게시글 찾기! (:title, :writer 방식)
        List<Board> list = boardRepository.findByTitleAndWriter3("title1", "writer1");
        assertTrue(list.size() == 1); // 역시 1개!
    }

    // 4. @Query로 네이티브 쿼리(SQL) 작성 테스트 (모든 컬럼 조회)
    @Test
    @DisplayName("@Query로 네이티브 쿼리(SQL) 작성 테스트")
    public void queryAnnoTest4() {
        List<Board> list = boardRepository.findAllBoardSQL(); // 네이티브 SQL 호출!
        assertTrue(list.size() == 100); // 100개 잘 찾아왔는지 확인!
    }

    // 5. @Query로 네이티브 쿼리(SQL) 작성 테스트 (일부 컬럼만 조회)
    @Test
    @DisplayName("@Query로 네이티브 쿼리(SQL) 작성 테스트2")
    public void queryAnnoTest5() {
        List<Object[]> list = boardRepository.findAllBoardSQL2(); // TITLE, WRITER만!
        list.stream() // 리스트를 스트림으로 변환
            .map(arr -> Arrays.toString(arr)) // 각 배열(Object[])을 문자열로 변환
            .forEach(System.out::println); // 화면에 출력
        assertTrue(list.size() == 100); // 100개의 [제목, 작성자] 쌍이 나왔는지!
    }

    // 6. EntityManager의 createQuery로 JPQL 작성 테스트
    @Test
    @DisplayName("createQuery로 JPQL작성 테스트")
    public void createQueryTest() {
        String query = "SELECT b FROM Board b"; // JPQL 문자열
        TypedQuery<Board> tQuery = em.createQuery(query, Board.class); // EntityManager로 쿼리 생성!
        List<Board> list = tQuery.getResultList(); // 결과 가져오기!
        // list.forEach(System.out::println); // 필요하면 출력해서 확인
        assertTrue(list.size() == 100);
    }
}

각 테스트는 @DisplayName으로 어떤 테스트인지 이름을 붙여줬고, @BeforeEach의 testData() 메서드 덕분에 항상 100개의 데이터가 있는 상태에서 시작해요. 그래서 각 테스트가 서로 영향을 주지 않고 독립적으로 잘 돌아가는지 확인할 수 있답니다!

---

🔑 정리 요약표

개념설명

JPQL	Entity 기준으로 작성하는 JPA 전용 SQL
@Query	JPQL 또는 SQL을 Repository에 직접 작성할 수 있음
Native Query	실제 DB용 SQL을 직접 작성 (nativeQuery=true)
createQuery()	EntityManager를 통해 JPQL 직접 실행
?1, ?2	순서 기반 매개변수
:이름	이름 기반 매개변수 (@Param 생략 가능)
List<Object[]>	일부 컬럼 조회할 때 사용하는 반환 타입

 

 

---

📌 마무리

오늘 우리는 Spring Data JPA에서 우리만의 특별한 데이터 조회 레시피를 만드는 두 가지 방법, JPQL과 네이티브 쿼리에 대해 배웠어요.

• JPQL은 우리가 만든 자바 엔티티 객체에게 말을 거는 방식이라 좀 더 객체지향적이고, 데이터베이스 종류가 바뀌어도 코드를 거의 고칠 필요가 없다는 장점이 있어요. (마치 표준어로 대화하는 것과 같죠!)
• 네이티브 쿼리는 데이터베이스에게 직접 그들의 언어(SQL)로 말을 거는 방식이라, 아주 특별하거나 복잡한 작업을 할 때, 또는 성능을 극한으로 끌어올리고 싶을 때 유용해요. (마치 특정 지역의 방언 전문가처럼요!)

Spring Data JPA의 @Query 어노테이션 덕분에 이 두 가지 방법을 아주 편리하게 사용할 수 있죠. 상황에 맞게 JPQL과 네이티브 쿼리를 잘 선택해서 사용한다면, 여러분도 데이터베이스와 자유자재로 대화하는 데이터 전문가가 될 수 있을 거예요! 🎉