From 8352ab39fb15874229b448f57b6909de933a91b1 Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Sat, 4 Feb 2012 17:16:26 -0600 Subject: [PATCH] HHH-6082 - Incorporate EntityManager documentation into main dev guide --- .../devguide/en-US/chapters/hql/HQL_JPQL.xml | 101 ++++++++++++++++++ .../hql/extras/group_by_illustration.txt | 10 ++ .../hql/extras/having_illustration.txt | 5 + .../chapters/hql/extras/order_by_example.txt | 10 ++ .../src/main/docbook/en/master.xml | 2 +- .../en/modules/{ => migrated}/query_ejbql.xml | 0 6 files changed, 127 insertions(+), 1 deletion(-) create mode 100644 documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/group_by_illustration.txt create mode 100644 documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/having_illustration.txt create mode 100644 documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/order_by_example.txt rename hibernate-entitymanager/src/main/docbook/en/modules/{ => migrated}/query_ejbql.xml (100%) diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml b/documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml index d9c097a5d3..30d20426a7 100644 --- a/documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/HQL_JPQL.xml @@ -1321,18 +1321,119 @@ + +
+ NOT predicate operator + + The NOT operator is used to negate the predicate that follows it. If that + following predicate is true, the NOT resolves to false. If the predicate is true, NOT resolves to + false. If the predicate is unknown, the NOT resolves to unknown as well. + +
+ +
+ AND predicate operator + + The AND operator is used to combine 2 predicate expressions. The result of the + AND expression is true if and only if both predicates resolve to true. If either predicate resolves + to unknown, the AND expression resolves to unknown as well. Otherwise, the result is false. + +
+ +
+ OR predicate operator + + The OR operator is used to combine 2 predicate expressions. The result of the + OR expression is true if either predicate resolves to true. If both predicates resolve to unknown, the + OR expression resolves to unknown. Otherwise, the result is false. + +
The <literal>WHERE</literal> clause + + The WHERE clause of a query is made up of predicates which assert whether values in + each potential row match the predicated checks. Thus, the where clause restricts the results returned + from a select query and limits the scope of update and delete queries. +
Grouping + + The GROUP BY clause allows building aggregated results for various value groups. As an + example, consider the following queries: + + + Group-by illustration + + + + The first query retrieves the complete total of all orders. The second retrieves the total for each + customer; grouped by each customer. + + + In a grouped query, the where clause applies to the non aggregated values (essentially it determines whether + rows will make it into the aggregation). The HAVING clause also restricts results, + but it operates on the aggregated values. In the example, + we retrieved order totals for all customers. If that ended up being too much data to deal with, + we might want to restrict the results to focus only on customers with a summed order total of more than + $10,000.00: + + + Having illustration + + + + The HAVING clause follows the same rules as the WHERE clause and is also made up of predicates. HAVING is + applied after the groupings and aggregations have been done; WHERE is applied before. +
Ordering + + The results of the query can also be ordered. The ORDER BY clause is used to specify + the selected values to be used to order the result. The types of expressions considered valid as part + of the order-by clause include: + + + + + state fields + + + + + component/embeddable attributes + + + + + scalar expressions such as arithmetic operations, functions, etc. + + + + + identification variable declared in the select clause for any of the previous expression types + + + + + Additionally, JPQL says that all values referenced in the order-by clause must be named in the select + clause. HQL does not mandate that restriction, but applications desiring database portability should be + aware that not all databases support referencing values in the order-by clause that are not referenced + in the select clause. + + + Individual expressions in the order-by can be qualified with either ASC (ascending) or + DESC (descending) to indicated the desired ordering direction. + + + Order-by examples + +
diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/group_by_illustration.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/group_by_illustration.txt new file mode 100644 index 0000000000..598d20c5f8 --- /dev/null +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/group_by_illustration.txt @@ -0,0 +1,10 @@ +// retrieve the total for all orders +select sum( o.total ) +from Order o + +// retrieve the total of all orders +// *grouped by* customer +select c.id, sum( o.total ) +from Order o + inner join o.customer c +group by c.id \ No newline at end of file diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/having_illustration.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/having_illustration.txt new file mode 100644 index 0000000000..60f39b3c4a --- /dev/null +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/having_illustration.txt @@ -0,0 +1,5 @@ +select c.id, sum( o.total ) +from Order o + inner join o.customer c +group by c.id +having sum( o.total ) > 10000.00 \ No newline at end of file diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/order_by_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/order_by_example.txt new file mode 100644 index 0000000000..71b6024fee --- /dev/null +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/order_by_example.txt @@ -0,0 +1,10 @@ +// legal because p.name is implicitly part of p +select p +from Person p +order by p.name + +select c.id, sum( o.total ) as t +from Order o + inner join o.customer c +group by c.id +order by t diff --git a/hibernate-entitymanager/src/main/docbook/en/master.xml b/hibernate-entitymanager/src/main/docbook/en/master.xml index f5cf799b11..b828fd9f7d 100644 --- a/hibernate-entitymanager/src/main/docbook/en/master.xml +++ b/hibernate-entitymanager/src/main/docbook/en/master.xml @@ -120,7 +120,7 @@ -