Hibernate HQL 查詢實戰範例：參數綁定、分頁、導航、原生 SQL 與資料庫函數

前言

HQL (Hibernate Query Language) 是面向物件的查詢語言，支援多種參數綁定方式、導航查詢、分頁、資料庫函數呼叫及原生 SQL。本文以 Student 實體為例，系統展示 8 種常用查詢模式。

實體定義假設

class Student {
    Long id;
    String name;
    Date createTime;
    Classes classes; // 關聯實體
}

八大查詢模式

1. 字串內嵌參數 (不推薦，有注入風險)

List students = session.createQuery(
    "select s.id, s.name from Student s where s.name like '%1'").list();
for (Object[] o : students) System.out.println(o[0] + "," + o[1]);

2. 命名參數 (:name) — 推薦

List students = session.createQuery(
    "select s.id, s.name from Student s where s.name like :goodname")
    .setParameter("goodname", "%1%").list();

3. 位置參數 (?) — 類似 PreparedStatement

List students = session.createQuery(
    "select s.id, s.name from Student s where s.name like ?")
    .setParameter(0, "%1%").list(); // 索引從 0 開始

4. 多值參數 (IN 子句)

List students = session.createQuery(
    "select s.id, s.name from Student s where s.id in (:myids)")
    .setParameterList("myids", new Object[]{1,2,3,4,5,32,13,14}).list();

5. 呼叫資料庫函數

List students = session.createQuery(
    "select s.id, s.name from Student s where date_format(s.createTime, '%Y-%m') = ?")
    .setParameter(0, "2008-10").list();
// date_format 為 MySQL 函數，跨資料庫需注意方言

6. 原生 SQL 查詢

List students = session.createSQLQuery("select * from t_student").list();
// 回傳 Object[]，欄位順序對應資料表定義

7. 導航查詢 (關聯屬性)

List names = session.createQuery(
    "select s.name from Student s where s.classes.name like '%1%'").list();
// 自動產生 INNER JOIN，無需手寫 JOIN 子句

8. 分頁查詢

List students = session.createQuery("from Student")
    .setFirstResult(0).setMaxResults(3).list();
// 相當於 LIMIT 0,3 (MySQL) 或 ROWNUM (Oracle)

進階主題提示

• 查詢快取：query.setCacheable(true) 搭配二級快取提升重複查詢效能
• 投影查詢：select new DTO(s.id, s.name) from Student s 直接映射至 DTO，避免 Object[]
• 批次抓取：@BatchSize(size=10) 減少 N+1 問題
• Criteria API：型別安全、動態組裝查詢，適合複雜條件

最佳實踐總結