第 11 章 Hibernate查询语言(Query Language), 即HQL - Hibernate reference 2.1.8 ga 正式版中文参考手册

除了Java类和属性名称外，查询都是大小写不敏感的。 所以， SeLeCT 和 sELEct 以及 SELECT 相同的，但是 net.sf.hibernate.eg.FOO 和 net.sf.hibernate.eg.Foo 是不同的， foo.barSet 和 foo.BARSET也是不同的。

本手册使用小写的HQL关键词。有些用户认为在查询中使用大写的关键字更加易读，但是我们认为嵌入在Java代码中这样很难看。

可能最简单的Hibernate查询是这样的形式：

from eg.Cat

它简单的返回所有eg.Cat类的实例。

大部分情况下，你需要赋予它一个别名（alias），因为你在查询的其他地方也会引用这个Cat。

from eg.Cat as cat

上面的语句为Cat赋予了一个别名cat 。所以后面的查询可以用这个简单的别名了。as关键字是可以省略的，我们也可以写成这样：

from eg.Cat cat

可以出现多个类，结果是它们的笛卡尔积，或者称为“交叉”连接。

from Formula, Parameter

from Formula as form, Parameter as param

让查询中的别名服从首字母小写的规则，我们认为这是一个好习惯。这和Java对局部变量的命名规范是一致的。(比如，domesticCat).

你可以使用join定义两个实体的连接，同时指明别名。

from eg.Cat as cat 
    inner join cat.mate as mate
    left outer join cat.kittens as kitten

from eg.Cat as cat left join cat.mate.kittens as kittens

from Formula form full join form.parameter param

支持的连接类型是从ANSI SQL借用的：

inner join, left outer join 和 right outer join 都可以简写。

from eg.Cat as cat 
    join cat.mate as mate
    left join cat.kittens as kitten

并且，加上 "fetch"后缀的抓取连接可以让联合的对象随着它们的父对象的初始化而初始化，只需要一个select语句。这在初始化一个集合的时候特别有用。它有效地覆盖了映射文件中对关联和集合的外连接定义。

from eg.Cat as cat 
    inner join fetch cat.mate
    left join fetch cat.kittens

抓取连接一般不需要赋予别名，因为被联合的对象应该不会在where子句（或者任何其它子句）中出现。并且，被联合的对象也不会在查询结果中直接出现。它们是通过父对象进行访问的。

请注意，目前的实现中，在一次查询中只会抓取一个集合（其他的一切都做不到。）（？原文为：only one collection role may be fetched in a query）。也请注意，在使用scroll()或者 iterate()方式调用的查询中，是禁止使用fetch构造的。最后，请注意full join fetch和right join fetch是没有意义的。

select子句选择在结果集中返回哪些对象和属性。思考一下下面的例子：

select mate 
from eg.Cat as cat 
    inner join cat.mate as mate

这个查询会选择出作为其它猫（Cat）朋友（mate）的那些猫。当然，你可以更加直接的写成下面的形式：

select cat.mate from eg.Cat cat

你甚至可以选择集合元素，使用特殊的elements功能。下面的查询返回所有猫的小猫。

select elements(cat.kittens) from eg.Cat cat

查询可以返回任何值类型的属性，包括组件类型的属性：

select cat.name from eg.DomesticCat cat
where cat.name like 'fri%'

select cust.name.firstName from Customer as cust

查询可以用元素类型是Object[]的一个数组返回多个对象和/或多个属性。

select mother, offspr, mate.name 
from eg.DomesticCat as mother
    inner join mother.mate as mate
    left outer join mother.kittens as offspr

或者实际上是类型安全的Java对象

select new Family(mother, mate, offspr)
from eg.DomesticCat as mother
    join mother.mate as mate
    left join mother.kittens as offspr

上面的代码假定Family有一个合适的构造函数。

HQL查询可以返回属性的统计函数的结果。

select avg(cat.weight), sum(cat.weight), max(cat.weight), count(cat)
from eg.Cat cat

在select子句中，统计函数的变量也可以是集合。

select cat, count( elements(cat.kittens) ) 
from eg.Cat cat group by cat

下面是支持的统计函数列表：

distinct 和 all关键字的用法和语义与SQL相同。

select distinct cat.name from eg.Cat cat

select count(distinct cat.name), count(cat) from eg.Cat cat

类似下面的查询：

from eg.Cat as cat

返回的实例不仅仅是Cat，也有可能是子类的实例，比如DomesticCat。Hibernate查询可以在from子句中使用任何Java类或者接口的名字。查询可能返回所有继承自这个类或者实现这个接口的持久化类的实例。下列查询会返回所有的持久化对象：

from java.lang.Object o

可能有多个持久化类都实现了Named接口：

from eg.Named n, eg.Named m where n.name = m.name

请注意，上面两个查询都使用了超过一个SQL的SELECT。这意味着order by子句将不会正确排序。（这也意味着你不能对这些查询使用Query.scroll()。）

where子句让你缩小你要返回的实例的列表范围。

from eg.Cat as cat where cat.name='Fritz'

返回所有名字为'Fritz'的Cat的实例。

select foo 
from eg.Foo foo, eg.Bar bar
where foo.startDate = bar.date

会返回所有的满足下列条件的Foo实例，它们存在一个对应的bar实例，其date属性与Foo的startDate属性相等。复合路径表达式令where子句变得极为有力。思考下面的例子：

from eg.Cat cat where cat.mate.name is not null

这个查询会被翻译为带有一个表间（inner)join的SQL查询。如果你写下类似这样的语句：

from eg.Foo foo  
where foo.bar.baz.customer.address.city is not null

你最终会得到的查询，其对应的SQL需要4个表间连接。

=操作符不仅仅用于判断属性是否相等，也可以用于实例：

from eg.Cat cat, eg.Cat rival where cat.mate = rival.mate

select cat, mate 
from eg.Cat cat, eg.Cat mate
where cat.mate = mate

特别的，小写的id可以用来表示一个对象的惟一标识。（你可以使用它的属性名。）

from eg.Cat as cat where cat.id = 123

from eg.Cat as cat where cat.mate.id = 69

第二个查询是很高效的。不需要进行表间连接！

组合的标示符也可以使用。假设Person有一个组合标示符，是由country和medicareNumber组合而成的。

from bank.Person person
where person.id.country = 'AU' 
    and person.id.medicareNumber = 123456

from bank.Account account
where account.owner.id.country = 'AU' 
    and account.owner.id.medicareNumber = 123456

又一次，第二个查询不需要表间连接。

类似的，在存在多态持久化的情况下，特殊属性class用于获取某个实例的辨识值。在where子句中嵌入的Java类名将会转换为它的辨识值。

from eg.Cat cat where cat.class = eg.DomesticCat

你也可以指定组件（或者是组件的组件，依次类推）或者组合类型中的属性。但是在一个存在路径的表达式中，最后不能以一个组件类型的属性结尾。（这里不是指组件的属性）。比如，假若store.owner这个实体的的address是一个组件

store.owner.address.city    //okay
store.owner.address         //error!

“任意(any)”类型也有特殊的id属性和class属性，这可以让我们用下面的形式来表达连接（这里AuditLog.item是一个对应到<ant>的属性）。

from eg.AuditLog log, eg.Payment payment 
where log.item.class = 'eg.Payment' and log.item.id = payment.id

注意上面查询中，log.item.class和payment.class会指向两个值，代表完全不同的数据库字段。

where子句允许出现的表达式包括了你在SQL中可以使用的大多数情况：

in 和 between 可以如下例一样使用:

from eg.DomesticCat cat where cat.name between 'A' and 'B'

from eg.DomesticCat cat where cat.name in ( 'Foo', 'Bar', 'Baz' )

其否定形式为

from eg.DomesticCat cat where cat.name not between 'A' and 'B'

from eg.DomesticCat cat where cat.name not in ( 'Foo', 'Bar', 'Baz' )

类似的，is null和is not null可以用来测试null值。

通过在Hibernate配置中声明HQL查询的替换方式，Boolean也是很容易在表达式中使用的：

<property name="hibernate.query.substitutions">true 1, false 0</property>

在从HQL翻译成SQL的时候,关键字true和false就会被替换成1和0。

from eg.Cat cat where cat.alive = true

你可以用特殊属性size来测试一个集合的长度，或者用特殊的size()函数也可以。

from eg.Cat cat where cat.kittens.size > 0

from eg.Cat cat where size(cat.kittens) > 0

对于排序集合，你可以用minIndex和maxIndex来获取其最大索引值和最小索引值。类似的，minElement 和maxElement 可以用来获取集合中最小和最大的元素，前提是必须是基本类型的集合。

from Calendar cal where cal.holidays.maxElement > current date

也有函数的形式（和上面的形式不同，函数形式是大小写不敏感的）：

from Order order where maxindex(order.items) > 100

from Order order where minelement(order.items) > 10000

SQL中的any, some, all, exists, in功能也是支持的，前提是必须把集合的元素或者索引集作为它们的参数（使用element和indices函数），或者使用子查询的结果作为参数。

select mother from eg.Cat as mother, eg.Cat as kit
where kit in elements(foo.kittens)

select p from eg.NameList list, eg.Person p
where p.name = some elements(list.names)

from eg.Cat cat where exists elements(cat.kittens)

from eg.Player p where 3 > all elements(p.scores)

from eg.Show show where 'fizard' in indices(show.acts)

请注意这些设施：size,elements,indices,minIndex,maxIndex,minElement,maxElement 都有一些使用限制：

有序的集合(数组、list、map)的元素可以用索引来进行引用（只限于在where子句中）

from Order order where order.items[0].id = 1234

select person from Person person, Calendar calendar
where calendar.holidays['national day'] = person.birthDay
    and person.nationality.calendar = calendar

select item from Item item, Order order
where order.items[ order.deliveredItemIndices[0] ] = item and order.id = 11

select item from Item item, Order order
where order.items[ maxindex(order.items) ] = item and order.id = 11

[]中的表达式允许是另一个数学表达式。

select item from Item item, Order order
where order.items[ size(order.items) - 1 ] = item

HQL也对一对多关联或者值集合提供内置的index()函数。

select item, index(item) from Order order 
    join order.items item
where index(item) < 5

底层数据库支持的标量SQL函数也可以使用

from eg.DomesticCat cat where upper(cat.name) like 'FRI%'

假如以上的这些还没有让你信服的话，请想象一下下面的查询假若用SQL来写，会变得多么长，多么不可读：

select cust
from Product prod,
    Store store
    inner join store.customers cust
where prod.name = 'widget'
    and store.location.name in ( 'Melbourne', 'Sydney' )
    and prod = all elements(cust.currentOrder.lineItems)

提示：对应的SQL语句可能是这样的

SELECT cust.name, cust.address, cust.phone, cust.id, cust.current_order
FROM customers cust,
    stores store,
    locations loc,
    store_customers sc,
    product prod
WHERE prod.name = 'widget'
    AND store.loc_id = loc.id
    AND loc.name IN ( 'Melbourne', 'Sydney' )
    AND sc.store_id = store.id
    AND sc.cust_id = cust.id
    AND prod.id = ALL(
        SELECT item.prod_id
        FROM line_items item, orders o
        WHERE item.order_id = o.id
            AND cust.current_order = o.id
    )

查询返回的列表可以按照任何返回的类或者组件的属性排序：

from eg.DomesticCat cat
order by cat.name asc, cat.weight desc, cat.birthdate

asc和desc是可选的，分别代表升序或者降序。

返回统计值的查询可以按照返回的类或者组件的任何属性排序：

select cat.color, sum(cat.weight), count(cat) 
from eg.Cat cat
group by cat.color

select foo.id, avg( elements(foo.names) ), max( indices(foo.names) ) 
from eg.Foo foo
group by foo.id

请注意：你可以在select子句中使用elements和indices指令，即使你的数据库不支持子查询也可以。

having子句也是允许的。

select cat.color, sum(cat.weight), count(cat) 
from eg.Cat cat
group by cat.color 
having cat.color in (eg.Color.TABBY, eg.Color.BLACK)

在having子句中允许出现SQL函数和统计函数，当然这需要底层数据库支持才行。（比如说,MySQL就不支持）

select cat
from eg.Cat cat
    join cat.kittens kitten
group by cat
having avg(kitten.weight) > 100
order by count(kitten) asc, sum(kitten.weight) desc

注意，group by子句和order by子句都不支持数学表达式。

对于支持子查询的数据库来说，Hibernate支持在查询中嵌套子查询。子查询必须由圆括号包围（常常是在一个SQL统计函数中）。也允许关联子查询（在外部查询中作为一个别名出现的子查询）。

from eg.Cat as fatcat 
where fatcat.weight > ( 
    select avg(cat.weight) from eg.DomesticCat cat 
)

from eg.DomesticCat as cat 
where cat.name = some ( 
    select name.nickName from eg.Name as name 
)
    
from eg.Cat as cat 
where not exists ( 
    from eg.Cat as mate where mate.mate = cat 
)

from eg.DomesticCat as cat 
where cat.name not in ( 
    select name.nickName from eg.Name as name 
)

Hibernate查询可以非常强大复杂。实际上，强有力的查询语言是Hibernate的主要卖点之一。下面给出的示例与我在近期实际项目中使用的一些查询很类似。请注意你编写的查询大部分等都不会这么复杂！

下面的查询对特定的客户，根据给定的最小总计值（minAmount)，查询出所有未付订单，返回其订单号、货品总数、订单总金额，结果按照总金额排序。在决定价格的时候，参考当前目录。产生的SQL查询，在ORDER,ORDER_LINE,PRODUCT,CATALOG和PRICE表之间有四个内部连接和一个没有产生关联的字查询。

select order.id, sum(price.amount), count(item)
from Order as order
    join order.lineItems as item
    join item.product as product,
    Catalog as catalog
    join catalog.prices as price
where order.paid = false
    and order.customer = :customer
    and price.product = product
    and catalog.effectiveDate < sysdate
    and catalog.effectiveDate >= all (
        select cat.effectiveDate 
        from Catalog as cat
        where cat.effectiveDate < sysdate
    )
group by order
having sum(price.amount) > :minAmount
order by sum(price.amount) desc

好家伙，真长！实际上，在现实生活中我并不是非常热衷于子查询，所以我的查询往往是这样的：

select order.id, sum(price.amount), count(item)
from Order as order
    join order.lineItems as item
    join item.product as product,
    Catalog as catalog
    join catalog.prices as price
where order.paid = false
    and order.customer = :customer
    and price.product = product
    and catalog = :currentCatalog
group by order
having sum(price.amount) > :minAmount
order by sum(price.amount) desc

下面的查询统计付款记录处于每种状态中的数量，要排除所有处于AWAITING_APPROVAL状态的，或者最近一次状态更改是由当前用户做出的。它翻译成SQL查询后，在PAYMENT,PAYMENT_STATUS和PAYMENT_STATUS_CHANGE表之间包含两个内部连接和一个用于关联的子查询。

select count(payment), status.name 
from Payment as payment 
    join payment.currentStatus as status
    join payment.statusChanges as statusChange
where payment.status.name <> PaymentStatus.AWAITING_APPROVAL
    or (
        statusChange.timeStamp = ( 
            select max(change.timeStamp) 
            from PaymentStatusChange change 
            where change.payment = payment
        )
        and statusChange.user <> :currentUser
    )
group by status.name, status.sortOrder
order by status.sortOrder

假若我已经把statusChange集合映射为一个列表而不是一个集合的话，查询写起来会简单很多。

select count(payment), status.name 
from Payment as payment
    join payment.currentStatus as status
where payment.status.name <> PaymentStatus.AWAITING_APPROVAL
    or payment.statusChanges[ maxIndex(payment.statusChanges) ].user <> :currentUser
group by status.name, status.sortOrder
order by status.sortOrder

下面的查询使用了MS SQL Server的isNull()函数，返回当前用户所属的组织所有账户和未付支出。翻译为SQL查询后，在ACCOUNT, PAYMENT, PAYMENT_STATUS,ACCOUNT_TYPE, ORGANIZATION 和 ORG_USER表之间有三个内部连接，一个外部连接和一个子查询。

select account, payment
from Account as account
    left outer join account.payments as payment
where :currentUser in elements(account.holder.users)
    and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID)
order by account.type.sortOrder, account.accountNumber, payment.dueDate

对某些数据库而言，我们可能不能依赖（关联的）子查询。

select account, payment
from Account as account
    join account.holder.users as user
    left outer join account.payments as payment
where :currentUser = user
    and PaymentStatus.UNPAID = isNull(payment.currentStatus.name, PaymentStatus.UNPAID)
order by account.type.sortOrder, account.accountNumber, payment.dueDate

你不返回结果集也可以查询结果集的大小：

( (Integer) session.iterate("select count(*) from ....").next() ).intValue()

要依据一个集合的大小对结果集排序，可以用下面的查询来对付一对多或多对多的关联：

select usr
from User as usr 
    left join usr.messages as msg
group by usr
order by count(msg)

如果你的数据库支持子查询，你可以在查询的where子句中对选择的大小进行条件限制：

from User usr where size(usr.messages) >= 1

如果你的数据库不支持子查询，可以使用下列查询：

select usr.id, usr.name
from User usr.name
    join usr.messages msg
group by usr.id, usr.name
having count(msg) >= 1

因为使用了inner join,这个解决方法不能返回没有message的User.下面的方式就可以：

select usr
from User as usr
    left join usr.messages as msg
group by usr
having count(msg) = 0

JavaBean的属性可以直接作为命名的查询参数：

Query q = s.createQuery("from foo in class Foo where foo.name=:name and foo.size=:size");
q.setProperties(fooBean); // fooBean has getName() and getSize()
List foos = q.list();

在Query接口中使用过滤器(filter),可以对集合分页：

Query q = s.createFilter( collection, "" ); // the trivial filter
q.setMaxResults(PAGE_SIZE);
q.setFirstResult(PAGE_SIZE * pageNumber);
List page = q.list();

集合元素可以使用查询过滤器(query filter)进行排序或者分组：

Collection orderedCollection = s.filter( collection, "order by this.amount" );
Collection counts = s.filter( collection, "select this.type, count(this) group by this.type" );

不用初始化集合就可以得到其大小：

( (Integer) session.iterate("select count(*) from ....").next() ).intValue();