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 b25eb9d191..d9c097a5d3 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 @@ -64,7 +64,7 @@ The BNF for SELECT statements in HQL is: - + The simplest possible HQL SELECT statement is of the form: @@ -86,7 +86,7 @@ The BNF for UPDATE statements is the same in HQL and JPQL: - + UPDATE statements, by default, do not effect the version or the timestamp attribute values for the affected entities. However, @@ -112,9 +112,9 @@ Example UPDATE query statements - - - + + + @@ -130,7 +130,7 @@ The BNF for DELETE statements is the same in HQL and JPQL: - + A DELETE statement is also executed using the executeUpdate method of either org.hibernate.Query or @@ -144,7 +144,7 @@ HQL adds the ability to define INSERT statements as well. There is no JPQL equivalent to this. The BNF for an HQL INSERT statement is: - + The attribute_list is analogous to the column specification in the SQL INSERT statement. For entities involved in mapped inheritance, only attributes @@ -179,7 +179,7 @@ Example INSERT query statements - + @@ -260,11 +260,11 @@ Explicit inner join examples - + Explicit left (outer) join examples - + An important use case for explicit joins is to define FETCH JOINS which override @@ -273,7 +273,7 @@ Fetch join example - + As you can see from the example, a fetch join is specified by injecting the keyword fetch @@ -304,7 +304,7 @@ with-clause join example - + The important distinction is that in the generated SQL the conditions of the @@ -329,7 +329,7 @@ Simple implicit join example - + An implicit join always starts from an identification variable, followed by @@ -355,7 +355,7 @@ Reused implicit join - + Just as with explicit joins, implicit joins may reference association or component/embedded attributes. @@ -533,7 +533,7 @@ - Entity names can also be used as literal. See entity type expressions below. + Entity names can also be used as literal. See . @@ -1032,7 +1032,7 @@ -
+
Entity type We can also refer to the type of an entity as an expression. This is mainly useful when dealing @@ -1158,24 +1158,24 @@
- Conditional expressions + Predicates - Conditional expressions form the basis of the where clause, the having clause and searched case expressions. + Predicates form the basis of the where clause, the having clause and searched case expressions. They are expressions which resolve to a truth value, generally TRUE or FALSE, although boolean comparisons involving NULLs generally resolve to UNKNOWN.
- Comparison expressions + Relational comparisons Comparisons involve one of the comparison operators - , >=, <, <=, <>]>. HQL also defines - as a comparison operator, equivalent to ]]>. The operands should be + as a comparison operator synonymous with ]]>. The operands should be of the same type. - Comparison expression examples - + Relational comparison examples + Comparisons can also involve subquery qualifiers - ALL, ANY, @@ -1187,7 +1187,7 @@ ALL subquery comparison qualifier example - + The ANY/SOME qualifier resolves to true if the comparison is true for some of (at least one of) the @@ -1196,23 +1196,23 @@
- Null check expressions + Nullness predicate Check a value for nullness. Can be applied to basic attribute references, entity references and parameters. HQL additionally allows it to be applied to component/embeddable types. - Nullness check expression examples - + Nullness checking examples +
- Like expressions + Like predicate Performs a like comparison on string values. The syntax is: - + The semantics follow that of the SQL like expression. The pattern_value is the pattern to attempt to match in the string_expression. Just like SQL, @@ -1227,29 +1227,70 @@ _ or % - Like expression examples - + Like predicate examples +
- Between expressions + Between predicate Analogous to the SQL between expression. Perform a evaluation that a value is within the range of 2 other values. All the operands should have comparable types. - Between expression examples - + Between predicate examples +
- In expressions + In predicate + + IN predicates performs a check that a particular value is in a list of values. + Its syntax is: + + + + The types of the single_valued_expression and the individual values in the + single_valued_list must be consistent. JPQL limits the valid types here + to string, numeric, date, time, timestamp, and enum types. In JPQL, + single_valued_expression can only refer to: + + + + + state fields, which is its term for simple attributes. Specifically this + excludes association and component/embedded attributes. + + + + + entity type expressions. See + + + + + In HQL, single_valued_expression can refer to a far more broad set of expression + types. Single-valued association are allowed. So are component/embedded attributes, although that + feature depends on the level of support for tuple or row value constructor syntax in + the underlying database. Additionally, HQL does not limit the value type in any way, though + application developers should be aware that different types may incur limited support based on + the underlying database vendor. This is largely the reason for the JPQL limitations. + + + The list of values can come from a number of different sources. In the + constructor_expression and collection_valued_input_parameter, the + list of values must not be empty; it must contain at least one value. + + + In predicate examples + +
- Exists expressions + Exists predicate Exists expressions test the existence of results from a subquery. The affirmative form returns true if the subquery result contains values. The negated form returns true if the subquery @@ -1258,7 +1299,7 @@
- Empty collection expressions + Empty collection predicate The IS [NOT] EMPTY expression applies to collection-valued path expressions. It checks whether the particular collection has any associated values. @@ -1270,7 +1311,7 @@
- Member-of collection expressions + Member-of collection predicate The [NOT] MEMBER [OF] expression applies to collection-valued path expressions. It checks whether a value is a member of the specified collection. diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/explicit_inner_join_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_explicit_inner.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/explicit_inner_join_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_explicit_inner.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/explicit_outer_join_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_explicit_outer.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/explicit_outer_join_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_explicit_outer.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/fetch_join_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_fetch.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/fetch_join_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_fetch.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/implicit_join_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_implicit.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/implicit_join_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_implicit.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/reused_implicit_join_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_implicit_reused.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/reused_implicit_join_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_implicit_reused.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/with_join_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_with.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/with_join_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/join_example_with.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/between_exp_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_between_example.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/between_exp_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_between_example.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/comparison_exp_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_comparison_example.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/comparison_exp_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_comparison_example.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/comparison_using_all_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_comparison_example_using_all.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/comparison_using_all_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_comparison_example_using_all.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_in_bnf.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_in_bnf.txt new file mode 100644 index 0000000000..a8f3daec41 --- /dev/null +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_in_bnf.txt @@ -0,0 +1,8 @@ +in_expression ::= single_valued_expression + [NOT] IN single_valued_list + +single_valued_list ::= constructor_expression | + (subquery) | + collection_valued_input_parameter + +constructor_expression ::= (expression[, expression]*) \ No newline at end of file diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_in_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_in_example.txt new file mode 100644 index 0000000000..8e0f3b97f5 --- /dev/null +++ b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_in_example.txt @@ -0,0 +1,36 @@ +select p +from Payment p +where type(p) in (CreditCardPayment, WireTransferPayment) + +select c +from Customer c +where c.hqAddress.state in ('TX', 'OK', 'LA', 'NM') + +select c +from Customer c +where c.hqAddress.state in ? + +select c +from Customer c +where c.hqAddress.state in ( + select dm.state + from DeliveryMetadata dm + where dm.salesTax is not null +) + +// Not JPQL compliant! +select c +from Customer c +where c.name in ( + ('John','Doe'), + ('Jane','Doe') +) + +// Not JPQL compliant! +select c +from Customer c +where c.chiefExecutive in ( + select p + from Person p + where ... +) \ No newline at end of file diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/like_exp_bnf.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_like_bnf.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/like_exp_bnf.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_like_bnf.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/like_exp_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_like_example.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/like_exp_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_like_example.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/null_check_example.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_nullness_example.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/null_check_example.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/predicate_nullness_example.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/delete_statement_bnf.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_delete_bnf.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/delete_statement_bnf.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_delete_bnf.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/insert_statement_bnf.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_insert_bnf.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/insert_statement_bnf.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_insert_bnf.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/insert_statement_named_id.java b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_insert_example_named_id.java similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/insert_statement_named_id.java rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_insert_example_named_id.java diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/select_statement_bnf.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_select_bnf.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/select_statement_bnf.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_select_bnf.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_bnf.txt b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_update_bnf.txt similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_bnf.txt rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_update_bnf.txt diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_hql.java b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_update_example_hql.java similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_hql.java rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_update_example_hql.java diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/versioned_update_statement_hql.java b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_update_example_hql_versioned.java similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/versioned_update_statement_hql.java rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_update_example_hql_versioned.java diff --git a/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_jpql.java b/documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_update_example_jpql.java similarity index 100% rename from documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/update_statement_jpql.java rename to documentation/src/main/docbook/devguide/en-US/chapters/hql/extras/statement_update_example_jpql.java