Castle ActiveRecord 進階：使用 HQL 實現複雜查詢與聚合操作

為什麼需要 HQL？

Find()、FindAll() 僅支援單表主鍵查詢與全表掃描。實際專案常需：多表聯結、條件篩選、分頁、聚合統計、模糊查詢等，**HQL (Hibernate Query Language)** 為面向物件的查詢語言，完美解決此類需求。

HQL 基本語法對照 SQL

實體關聯定義：一對多與多對一

[ActiveRecord("Users")]
public class Users : ActiveRecordBase
{
    // ... 主鍵與屬性略 ...
    private IList _news;
    [HasMany(typeof(News), Table = "News", ColumnKey = "User_Oid")]
    public IList News { get => _news; set => _news = value; }
}

[ActiveRecord("News")]
public class News : ActiveRecordBase
{
    // ... 主鍵與屬性略 ...
    private Users _users;
    [BelongsTo("User_Oid")]
    public Users Users { get => _users; set => _users = value; }
}

SimpleQuery：參數化條件查詢

using Castle.ActiveRecord.Queries;

public static IList FindByAuthor(string author)
{
    var query = new SimpleQuery(typeof(News), "FROM News n WHERE n.Author = ?", author);
    return (IList)ExecuteQuery(query);
}

• SimpleQuery 建構子：(Type rootType, string hql, params object[] parameters)
• ExecuteQuery 回傳 IList，需轉型。

ScalarQuery：聚合與標量查詢

public static int RecordCount()
{
    var query = new ScalarQuery(typeof(News), "SELECT COUNT(*) FROM News");
    return (int)ExecuteQuery(query);
}

模糊查詢與進階條件

public static IList FindByTitle(string title)
{
    var query = new SimpleQuery(typeof(News),
        "FROM News n WHERE n.Title LIKE ?", "%" + title + "%");
    return (IList)ExecuteQuery(query);
}

自訂查詢類別：繼承 ActiveRecordBaseQuery

當 HQL 無法表達極複雜邏輯（如動態組裝 WHERE、存儲過程呼叫），可繼承 ActiveRecordBaseQuery 並實作 Execute(ISession session) 直接操作 NHibernate Session。

總結

• HQL 以**類別與屬性**為查詢對象，而非資料表與欄位。
• SimpleQuery 適用於回傳實體集合的條件查詢；ScalarQuery 適用於 COUNT/SUM/AVG 等單一值。
• 參數化查詢（?）防止 SQL Injection 並自動處理型別轉換。
• 複雜報表查詢建議改用 NHibernate Criteria API 或原生 SQL (SQLQuery)。