Hibernate 原生 SQL 查詢詳解：createSQLQuery 方法與別名映射機制

前言

Hibernate 雖然提供了強大的 HQL 查詢語言，但在某些複雜場景（如資料庫特有函數、複雜連接、效能調優）下，仍需直接使用原生 SQL。Hibernate 透過 Session.createSQLQuery() 方法支援原生 SQL 查詢，關鍵在於理解「別名映射」機制，將 SQL 結果集正確映射到持久化實體或標量值。本文基於 Hibernate 2.1.6 版本，深入解析相關 API 與用法。

核心 API 解析

1. 單一實體映射

public Query createSQLQuery(String sql, String returnAlias, Class returnClass)

• sql：原生 SQL 語句，可包含 {alias.*} 佔位符代表實體所有欄位。
• returnAlias：SQL 中出現的表別名（對應 {alias.*} 中的 alias）。
• returnClass：映射的持久化實體類別。

範例：

String sql = "SELECT {cat.*} FROM CAT {cat} WHERE {cat}.ID = ?";
List cats = session.createSQLQuery(sql, "cat", Cat.class)
                   .setParameter(0, catId)
                   .list();

2. 多實體/多表映射

public Query createSQLQuery(String sql, String[] returnAliases, Class[] returnClasses)

• returnAliases：SQL 中多個表別名陣列。
• returnClasses：對應的持久化類別陣列。

適用於多表連接查詢，一次取回多種實體物件。

關鍵概念：別名與大括號語法

Hibernate 要求在 SQL 中使用 {alias.*} 或 {alias.property} 語法，明確指定欄位屬於哪個別名。這讓 Hibernate 能根據映射檔自動解析欄位名稱、型別轉換，避免手動處理 ResultSet。

參考文檔與進階學習

建議詳細閱讀 Hibernate 官方參考文檔第 13 章（querysql.html），其中完整說明了：

• 純標量查詢（addScalar()）
• 實體與標量混合查詢
• 命名查詢中定義原生 SQL
• 存儲過程呼叫

注意事項

4.1 不要查詢未映射的表或視圖。 原生 SQL 查詢的目標實體必須在 Hibernate 映射檔中定義，否則無法正確映射。

總結

掌握 createSQLQuery 的別名映射機制，是發揮 Hibernate 原生 SQL 查詢威力的關鍵。合理使用原生 SQL 可解決 HQL 難以表達的複雜查詢，同時保持物件關係映射的便利性。