961 lines
35 KiB
XML
961 lines
35 KiB
XML
<chapter id="queryhql">
|
|
<title>HQL: The Hibernate Query Language</title>
|
|
|
|
<para>
|
|
Hibernate is equiped with an extremely powerful query language that (quite intentionally)
|
|
looks very much like SQL. But don't be fooled by the syntax; HQL is fully object-oriented,
|
|
understanding notions like inheritence, polymorphism and association.
|
|
</para>
|
|
|
|
<sect1 id="queryhql-casesensitivity">
|
|
<title>Case Sensitivity</title>
|
|
|
|
<para>
|
|
Queries are case-insensitive, except for names of Java classes and properties.
|
|
So <literal>SeLeCT</literal> is the same as
|
|
<literal>sELEct</literal> is the same as
|
|
<literal>SELECT</literal> but
|
|
<literal>org.hibernate.eg.FOO</literal> is not
|
|
<literal>org.hibernate.eg.Foo</literal> and
|
|
<literal>foo.barSet</literal> is not
|
|
<literal>foo.BARSET</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
This manual uses lowercase HQL keywords. Some users find queries with uppercase keywords
|
|
more readable, but we find this convention ugly when embedded in Java code.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-from">
|
|
<title>The from clause</title>
|
|
|
|
<para>
|
|
The simplest possible Hibernate query is of the form:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat]]></programlisting>
|
|
|
|
<para>
|
|
which simply returns all instances of the class <literal>eg.Cat</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
Most of the time, you will need to assign an <emphasis>alias</emphasis>, since
|
|
you will want to refer to the <literal>Cat</literal> in other parts of the
|
|
query.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat as cat]]></programlisting>
|
|
|
|
<para>
|
|
This query assigns the alias <literal>cat</literal> to <literal>Cat</literal>
|
|
instances, so we could use that alias later in the query. The <literal>as</literal>
|
|
keyword is optional; we could also write:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat cat]]></programlisting>
|
|
|
|
<para>
|
|
Multiple classes may appear, resulting in a cartesian product or "cross" join.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from Formula, Parameter]]></programlisting>
|
|
<programlisting><![CDATA[from Formula as form, Parameter as param]]></programlisting>
|
|
|
|
<para>
|
|
It is considered good practice to name query aliases using an initial lowercase,
|
|
consistent with Java naming standards for local variables
|
|
(eg. <literal>domesticCat</literal>).
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-joins">
|
|
<title>Associations and joins</title>
|
|
|
|
<para>
|
|
We may also assign aliases to associated entities, or even to elements of a collection of
|
|
values, using a <literal>join</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
The supported join types are borrowed from ANSI SQL
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<literal>inner join</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>left outer join</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>right outer join</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>full join</literal> (not usually useful)
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The <literal>inner join</literal>, <literal>left outer join</literal> and
|
|
<literal>right outer join</literal> constructs may be abbreviated.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat as cat
|
|
join cat.mate as mate
|
|
left join cat.kittens as kitten]]></programlisting>
|
|
|
|
<para>
|
|
In addition, a "fetch" join allows associations or collections of values to be
|
|
initialized along with their parent objects, using a single select. This is particularly
|
|
useful in the case of a collection. It effectively overrides the outer join and
|
|
lazy declarations of the mapping file for associations and collections.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat as cat
|
|
inner join fetch cat.mate
|
|
left join fetch cat.kittens]]></programlisting>
|
|
|
|
<para>
|
|
A fetch join does not usually need to assign an alias, because the associated objects
|
|
should not be used in the <literal>where</literal> clause (or any other clause). Also,
|
|
the associated objects are not returned directly in the query results. Instead, they may
|
|
be accessed via the parent object.
|
|
</para>
|
|
|
|
<para>
|
|
Note that, in the current implementation, only one collection role may be fetched
|
|
in a query (everything else would be non-performant). Note also that the
|
|
<literal>fetch</literal> construct may not be used in queries called using
|
|
<literal>scroll()</literal> or <literal>iterate()</literal>. Finally, note that
|
|
<literal>full join fetch</literal> and <literal>right join fetch</literal> are not meaningful.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-select">
|
|
<title>The select clause</title>
|
|
|
|
<para>
|
|
The <literal>select</literal> clause picks which objects and properties to return in
|
|
the query result set. Consider:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select mate
|
|
from eg.Cat as cat
|
|
inner join cat.mate as mate]]></programlisting>
|
|
|
|
<para>
|
|
The query will select <literal>mate</literal>s of other <literal>Cat</literal>s.
|
|
Actually, you may express this query more compactly as:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select cat.mate from eg.Cat cat]]></programlisting>
|
|
|
|
<para>
|
|
You may even select collection elements, using the special <literal>elements</literal>
|
|
function. The following query returns all kittens of any cat.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select elements(cat.kittens) from eg.Cat cat]]></programlisting>
|
|
|
|
<para>
|
|
Queries may return properties of any value type including properties of component type:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select cat.name from eg.DomesticCat cat
|
|
where cat.name like 'fri%'
|
|
|
|
select cust.name.firstName from Customer as cust]]></programlisting>
|
|
|
|
<para>
|
|
Queries may return multiple objects and/or properties as an array of type
|
|
<literal>Object[]</literal>
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select mother, offspr, mate.name
|
|
from eg.DomesticCat as mother
|
|
inner join mother.mate as mate
|
|
left outer join mother.kittens as offspr]]></programlisting>
|
|
|
|
<para>
|
|
or as an actual typesafe Java object
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select new Family(mother, mate, offspr)
|
|
from eg.DomesticCat as mother
|
|
join mother.mate as mate
|
|
left join mother.kittens as offspr]]></programlisting>
|
|
|
|
<para>
|
|
assuming that the class <literal>Family</literal> has an appropriate constructor.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-aggregation">
|
|
<title>Aggregate functions</title>
|
|
|
|
<para>
|
|
HQL queries may even return the results of aggregate functions on properties:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select avg(cat.weight), sum(cat.weight), max(cat.weight), count(cat)
|
|
from eg.Cat cat]]></programlisting>
|
|
|
|
<para>
|
|
Collections may also appear inside aggregate functions in the <literal>select</literal>
|
|
clause.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select cat, count( elements(cat.kittens) )
|
|
from eg.Cat cat group by cat]]></programlisting>
|
|
|
|
<para>
|
|
The supported aggregate functions are
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<literal>avg(...), sum(...), min(...), max(...)</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>count(*)</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>count(...), count(distinct ...), count(all...)</literal>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
The <literal>distinct</literal> and <literal>all</literal> keywords may be used and have
|
|
the same semantics as in SQL.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select distinct cat.name from eg.Cat cat
|
|
|
|
select count(distinct cat.name), count(cat) from eg.Cat cat]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-polymorphism">
|
|
<title>Polymorphic queries</title>
|
|
|
|
<para>
|
|
A query like:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat as cat]]></programlisting>
|
|
|
|
<para>
|
|
returns instances not only of <literal>Cat</literal>, but also of subclasses like
|
|
<literal>DomesticCat</literal>. Hibernate queries may name <emphasis>any</emphasis> Java
|
|
class or interface in the <literal>from</literal> clause. The query will return instances
|
|
of all persistent classes that extend that class or implement the interface. The following
|
|
query would return all persistent objects:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from java.lang.Object o]]></programlisting>
|
|
|
|
<para>
|
|
The interface <literal>Named</literal> might be implemented by various persistent
|
|
classes:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Named n, eg.Named m where n.name = m.name]]></programlisting>
|
|
|
|
<para>
|
|
Note that these last two queries will require more than one SQL <literal>SELECT</literal>. This
|
|
means that the <literal>order by</literal> clause does not correctly order the whole result set.
|
|
(It also means you can't call these queries using <literal>Query.scroll()</literal>.)
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-where">
|
|
<title>The where clause</title>
|
|
|
|
<para>
|
|
The <literal>where</literal> clause allows you to narrow the list of instances returned.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat as cat where cat.name='Fritz']]></programlisting>
|
|
|
|
<para>
|
|
returns instances of <literal>Cat</literal> named 'Fritz'.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select foo
|
|
from eg.Foo foo, eg.Bar bar
|
|
where foo.startDate = bar.date]]></programlisting>
|
|
|
|
<para>
|
|
will return all instances of <literal>Foo</literal> for which
|
|
there exists an instance of <literal>bar</literal> with a
|
|
<literal>date</literal> property equal to the
|
|
<literal>startDate</literal> property of the
|
|
<literal>Foo</literal>. Compound path expressions make the
|
|
<literal>where</literal> clause extremely powerful. Consider:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat cat where cat.mate.name is not null]]></programlisting>
|
|
|
|
<para>
|
|
This query translates to an SQL query with a table (inner) join. If you were to write
|
|
something like
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Foo foo
|
|
where foo.bar.baz.customer.address.city is not null]]></programlisting>
|
|
|
|
<para>
|
|
you would end up with a query that would require four table joins in SQL.
|
|
</para>
|
|
|
|
<para>
|
|
The <literal>=</literal> operator may be used to compare not only properties, but also
|
|
instances:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
The special property (lowercase) <literal>id</literal> may be used to reference the
|
|
unique identifier of an object. (You may also use its property name.)
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat as cat where cat.id = 123
|
|
|
|
from eg.Cat as cat where cat.mate.id = 69]]></programlisting>
|
|
|
|
<para>
|
|
The second query is efficient. No table join is required!
|
|
</para>
|
|
|
|
<para>
|
|
Properties of composite identifiers may also be used. Suppose <literal>Person</literal>
|
|
has a composite identifier consisting of <literal>country</literal> and
|
|
<literal>medicareNumber</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
Once again, the second query requires no table join.
|
|
</para>
|
|
|
|
<para>
|
|
Likewise, the special property <literal>class</literal> accesses the discriminator value
|
|
of an instance in the case of polymorphic persistence. A Java class name embedded in the
|
|
where clause will be translated to its discriminator value.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat cat where cat.class = eg.DomesticCat]]></programlisting>
|
|
|
|
<para>
|
|
You may also specify properties of components or composite user types (and of components
|
|
of components, etc). Never try to use a path-expression that ends in a property of component
|
|
type (as opposed to a property of a component). For example, if <literal>store.owner</literal>
|
|
is an entity with a component <literal>address</literal>
|
|
</para>
|
|
|
|
<programlisting><![CDATA[store.owner.address.city // okay
|
|
store.owner.address // error!]]></programlisting>
|
|
|
|
<para>
|
|
An "any" type has the special properties <literal>id</literal> and <literal>class</literal>,
|
|
allowing us to express a join in the following way (where <literal>AuditLog.item</literal>
|
|
is a property mapped with <literal><any></literal>).
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.AuditLog log, eg.Payment payment
|
|
where log.item.class = 'eg.Payment' and log.item.id = payment.id]]></programlisting>
|
|
|
|
<para>
|
|
Notice that <literal>log.item.class</literal> and <literal>payment.class</literal>
|
|
would refer to the values of completely different database columns in the above query.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-expressions">
|
|
<title>Expressions</title>
|
|
|
|
<para>
|
|
Expressions allowed in the <literal>where</literal> clause include
|
|
most of the kind of things you could write in SQL:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
mathematical operators <literal>+, -, *, /</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
binary comparison operators <literal>=, >=, <=, <>, !=, like</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
logical operations <literal>and, or, not</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
string concatenation ||
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
SQL scalar functions like <literal>upper()</literal> and
|
|
<literal>lower()</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Parentheses <literal>( )</literal> indicate grouping
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>in</literal>,
|
|
<literal>between</literal>,
|
|
<literal>is null</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
JDBC IN parameters <literal>?</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
named parameters <literal>:name</literal>, <literal>:start_date</literal>, <literal>:x1</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
SQL literals <literal>'foo'</literal>, <literal>69</literal>, <literal>'1970-01-01 10:00:01.0'</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Java <literal>public static final</literal> constants <literal>eg.Color.TABBY</literal>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
<literal>in</literal> and <literal>between</literal> may be used as follows:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.DomesticCat cat where cat.name between 'A' and 'B'
|
|
|
|
from eg.DomesticCat cat where cat.name in ( 'Foo', 'Bar', 'Baz' )]]></programlisting>
|
|
|
|
<para>
|
|
and the negated forms may be written
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.DomesticCat cat where cat.name not between 'A' and 'B'
|
|
|
|
from eg.DomesticCat cat where cat.name not in ( 'Foo', 'Bar', 'Baz' )]]></programlisting>
|
|
|
|
<para>
|
|
Likewise, <literal>is null</literal> and <literal>is not null</literal> may be used to test
|
|
for null values.
|
|
</para>
|
|
|
|
<para>
|
|
Booleans may be easily used in expressions by declaring HQL query substitutions in Hibernate
|
|
configuration:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<property name="hibernate.query.substitutions">true 1, false 0</property>]]></programlisting>
|
|
|
|
<para>
|
|
This will replace the keywords <literal>true</literal> and <literal>false</literal> with the
|
|
literals <literal>1</literal> and <literal>0</literal> in the translated SQL from this HQL:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat cat where cat.alive = true]]></programlisting>
|
|
|
|
<para>
|
|
You may test the size of a collection with the special property <literal>size</literal>, or
|
|
the special <literal>size()</literal> function.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.Cat cat where cat.kittens.size > 0
|
|
|
|
from eg.Cat cat where size(cat.kittens) > 0]]></programlisting>
|
|
|
|
<para>
|
|
For indexed collections, you may refer to the minimum and maximum indices using
|
|
<literal>minIndex</literal> and <literal>maxIndex</literal>. Similarly, you may refer to the
|
|
minimum and maximum elements of a collection of basic type using <literal>minElement</literal>
|
|
and <literal>maxElement</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from Calendar cal where cal.holidays.maxElement > current date]]></programlisting>
|
|
|
|
<para>
|
|
There are also functional forms (which, unlike the constructs above, are not case sensitive):
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from Order order where maxindex(order.items) > 100
|
|
|
|
from Order order where minelement(order.items) > 10000]]></programlisting>
|
|
|
|
<para>
|
|
The SQL functions <literal>any, some, all, exists, in</literal> are supported when passed the element
|
|
or index set of a collection (<literal>elements</literal> and <literal>indices</literal> functions)
|
|
or the result of a subquery (see below).
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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)]]></programlisting>
|
|
|
|
<para>
|
|
Note that these constructs - <literal>size</literal>, <literal>elements</literal>,
|
|
<literal>indices</literal>, <literal>minIndex</literal>, <literal>maxIndex</literal>,
|
|
<literal>minElement</literal>, <literal>maxElement</literal> - have certain usage
|
|
restrictions:
|
|
</para>
|
|
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
in a <literal>where</literal> clause: only for databases with subselects
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
in a <literal>select</literal> clause: only <literal>elements</literal> and
|
|
<literal>indices</literal> make sense
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
Elements of indexed collections (arrays, lists, maps) may be referred to by
|
|
index (in a where clause only):
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
The expression inside <literal>[]</literal> may even be an arithmetic expression.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select item from Item item, Order order
|
|
where order.items[ size(order.items) - 1 ] = item]]></programlisting>
|
|
|
|
<para>
|
|
HQL also provides the built-in <literal>index()</literal> function, for elements of
|
|
a one-to-many association or collection of values.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select item, index(item) from Order order
|
|
join order.items item
|
|
where index(item) < 5]]></programlisting>
|
|
|
|
<para>
|
|
Scalar SQL functions supported by the underlying database may be used
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.DomesticCat cat where upper(cat.name) like 'FRI%']]></programlisting>
|
|
|
|
<para>
|
|
If you are not yet convinced by all this, think how much longer and less readable the
|
|
following query would be in SQL:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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)]]></programlisting>
|
|
|
|
<para>
|
|
<emphasis>Hint:</emphasis> something like
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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
|
|
)]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-ordering">
|
|
<title>The order by clause</title>
|
|
|
|
<para>
|
|
The list returned by a query may be ordered by any property of a returned class or components:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from eg.DomesticCat cat
|
|
order by cat.name asc, cat.weight desc, cat.birthdate]]></programlisting>
|
|
|
|
<para>
|
|
The optional <literal>asc</literal> or <literal>desc</literal> indicate ascending or descending order
|
|
respectively.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-grouping">
|
|
<title>The group by clause</title>
|
|
|
|
<para>
|
|
A query that returns aggregate values may be grouped by any property of a returned class or components:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
Note: You may use the <literal>elements</literal> and <literal>indices</literal> constructs
|
|
inside a select clause, even on databases with no subselects.
|
|
</para>
|
|
|
|
<para>
|
|
A <literal>having</literal> clause is also allowed.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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)]]></programlisting>
|
|
|
|
<para>
|
|
SQL functions and aggregate functions are allowed in the <literal>having</literal>
|
|
and <literal>order by</literal> clauses, if supported by the underlying database (ie.
|
|
not in MySQL).
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
Note that neither the <literal>group by</literal> clause nor the
|
|
<literal>order by</literal> clause may contain arithmetic expressions.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-subqueries">
|
|
<title>Subqueries</title>
|
|
|
|
<para>
|
|
For databases that support subselects, Hibernate supports subqueries within queries. A subquery must
|
|
be surrounded by parentheses (often by an SQL aggregate function call). Even correlated subqueries
|
|
(subqueries that refer to an alias in the outer query) are allowed.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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
|
|
)]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-examples">
|
|
<title>HQL examples</title>
|
|
|
|
<para>
|
|
Hibernate queries can be quite powerful and complex. In fact, the power of the query language
|
|
is one of Hibernate's main selling points. Here are some example queries very similar to queries
|
|
that I used on a recent project. Note that most queries you will write are much simpler than these!
|
|
</para>
|
|
|
|
<para>
|
|
The following query returns the order id, number of items and total value of the order for all
|
|
unpaid orders for a particular customer and given minimum total value, ordering the results by
|
|
total value. In determining the prices, it uses the current catalog. The resulting SQL query,
|
|
against the <literal>ORDER</literal>, <literal>ORDER_LINE</literal>, <literal>PRODUCT</literal>,
|
|
<literal>CATALOG</literal> and <literal>PRICE</literal> tables has four inner joins and an
|
|
(uncorrelated) subselect.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
What a monster! Actually, in real life, I'm not very keen on subqueries, so my query was
|
|
really more like this:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
The next query counts the number of payments in each status, excluding all payments in the
|
|
<literal>AWAITING_APPROVAL</literal> status where the most recent status change was made by the
|
|
current user. It translates to an SQL query with two inner joins and a correlated subselect
|
|
against the <literal>PAYMENT</literal>, <literal>PAYMENT_STATUS</literal> and
|
|
<literal>PAYMENT_STATUS_CHANGE</literal> tables.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
If I would have mapped the <literal>statusChanges</literal> collection as a list, instead of a set,
|
|
the query would have been much simpler to write.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
The next query uses the MS SQL Server <literal>isNull()</literal> function to return all
|
|
the accounts and unpaid payments for the organization to which the current user belongs.
|
|
It translates to an SQL query with three inner joins, an outer join and a subselect against
|
|
the <literal>ACCOUNT</literal>, <literal>PAYMENT</literal>, <literal>PAYMENT_STATUS</literal>,
|
|
<literal>ACCOUNT_TYPE</literal>, <literal>ORGANIZATION</literal> and
|
|
<literal>ORG_USER</literal> tables.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
<para>
|
|
For some databases, we would need to do away with the (correlated) subselect.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="queryhql-tipstricks">
|
|
<title>Tips & Tricks</title>
|
|
|
|
<para>
|
|
You can count the number of query results without actually returning them:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[( (Integer) session.iterate("select count(*) from ....").next() ).intValue()]]></programlisting>
|
|
|
|
<para>
|
|
To order a result by the size of a collection, use the following query:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select usr.id, usr.name
|
|
from User as usr
|
|
left join usr.messages as msg
|
|
group by usr.id, usr.name
|
|
order by count(msg)]]></programlisting>
|
|
|
|
<para>
|
|
If your database supports subselects, you can place a condition upon selection
|
|
size in the where clause of your query:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[from User usr where size(usr.messages) >= 1]]></programlisting>
|
|
|
|
<para>
|
|
If your database doesn't support subselects, use the following query:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select usr.id, usr.name
|
|
from User usr.name
|
|
join usr.messages msg
|
|
group by usr.id, usr.name
|
|
having count(msg) >= 1]]></programlisting>
|
|
|
|
<para>
|
|
As this solution can't return a <literal>User</literal> with zero messages
|
|
because of the inner join, the following form is also useful:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[select usr.id, usr.name
|
|
from User as usr
|
|
left join usr.messages as msg
|
|
group by usr.id, usr.name
|
|
having count(msg) = 0]]></programlisting>
|
|
|
|
<para>
|
|
Properties of a JavaBean can be bound to named query parameters:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[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();]]></programlisting>
|
|
|
|
<para>
|
|
Collections are pageable by using the <literal>Query</literal> interface with a filter:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Query q = s.createFilter( collection, "" ); // the trivial filter
|
|
q.setMaxResults(PAGE_SIZE);
|
|
q.setFirstResult(PAGE_SIZE * pageNumber);
|
|
List page = q.list();]]></programlisting>
|
|
|
|
<para>
|
|
Collection elements may be ordered or grouped using a query filter:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Collection orderedCollection = s.filter( collection, "order by this.amount" );
|
|
Collection counts = s.filter( collection, "select this.type, count(this) group by this.type" );]]></programlisting>
|
|
|
|
<para>
|
|
You can find the size of a collection without initializing it:
|
|
</para>
|
|
|
|
<programlisting><![CDATA[( (Integer) session.iterate("select count(*) from ....").next() ).intValue();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|
|
|