From 09dd5daa73036ce7028975143fc15b27158a9d24 Mon Sep 17 00:00:00 2001 From: Gavin King Date: Thu, 10 Aug 2023 20:18:08 +0200 Subject: [PATCH] HHH-16973 document optional 'from' clause and use it in @HQL examples --- .../main/asciidoc/introduction/Generator.adoc | 18 +++++++++--------- .../asciidoc/introduction/Introduction.adoc | 2 +- .../main/asciidoc/querylanguage/Concepts.adoc | 19 ++++++++++++++++++- .../extras/statement_select_bnf.txt | 1 + 4 files changed, 29 insertions(+), 11 deletions(-) diff --git a/documentation/src/main/asciidoc/introduction/Generator.adoc b/documentation/src/main/asciidoc/introduction/Generator.adoc index c7c9bd390a..e92b31d357 100644 --- a/documentation/src/main/asciidoc/introduction/Generator.adoc +++ b/documentation/src/main/asciidoc/introduction/Generator.adoc @@ -146,7 +146,7 @@ Let's just stick it on the `Book` class: ---- @CheckHQL // validate the query at compile time @NamedQuery(name = "#findByTitleAndType", - query = "select book from Book book where book.title like :titlen and book.type = :type") + query = "select book from Book book where book.title like :titlen and book.type = :type") @Entity public class Book { ... } ---- @@ -189,7 +189,7 @@ We'll need a place to put this method, and since our `Book` entity isn't an abst [source,java] ---- interface Queries { - @HQL("from Book where title like :title and type = :type") + @HQL("where title like :title and type = :type") List findBooksByTitleAndType(String title, String type); } ---- @@ -216,7 +216,7 @@ public abstract class Queries_ { } static final String FIND_BOOKS_BY_TITLE_AND_TYPE_String_Type = - "from Book where title like :title and type = :type"; + "where title like :title and type = :type"; } @@ -229,7 +229,7 @@ If we want to explicitly specify the name and type of this parameter, we may dec [source,java] ---- interface Queries { - @HQL("from Book where title like :title and type = :type") + @HQL("where title like :title and type = :type") List findBooksByTitleAndType(StatelessSession session, String title, String type); } ---- @@ -277,7 +277,7 @@ We may call this method anything we like: interface Queries { EntityManager entityManager(); - @HQL("from Book where title like :title and type = :type") + @HQL("where title like :title and type = :type") List findBooksByTitleAndType(String title, String type); } ---- @@ -316,7 +316,7 @@ public class Queries_ implements Queries { } static final String FIND_BOOKS_BY_TITLE_AND_TYPE_String_Type = - "from Book where title like :title and type = :type"; + "where title like :title and type = :type"; } ---- @@ -342,7 +342,7 @@ interface Queries { // handwritten method replacing previous generated implementation default List findBooksByTitleAndType(String title, String type) { entityManager() - .createQuery("from Book where title like :title and type = :type", Book.class) + .createQuery("where title like :title and type = :type", Book.class) .setParameter("title", title) .setParameter("type", type) .setFlushMode(COMMIT) @@ -558,7 +558,7 @@ It might return a single `Book`. [source,java] ---- -@HQL("from Book where isbn = :isbn") +@HQL("where isbn = :isbn") Book findBookByIsbn(String isbn); ---- @@ -592,7 +592,7 @@ A query method might even return `TypedQuery` or `SelectionQuery`: [source,java] ---- -@HQL("from Book where title like :title") +@HQL("where title like :title") SelectionQuery findBooksByTitle(String title); ---- diff --git a/documentation/src/main/asciidoc/introduction/Introduction.adoc b/documentation/src/main/asciidoc/introduction/Introduction.adoc index 5ceb75d900..a53139f97d 100644 --- a/documentation/src/main/asciidoc/introduction/Introduction.adoc +++ b/documentation/src/main/asciidoc/introduction/Introduction.adoc @@ -554,7 +554,7 @@ Suppose we simplify `Queries` to just the following: [source,java] ---- interface Queries { - @HQL("from Book where title like :title order by title") + @HQL("where title like :title order by title") List findBooksByTitleWithPagination(String title, Page page); } ---- diff --git a/documentation/src/main/asciidoc/querylanguage/Concepts.adoc b/documentation/src/main/asciidoc/querylanguage/Concepts.adoc index c865ff5449..250cf229f3 100644 --- a/documentation/src/main/asciidoc/querylanguage/Concepts.adoc +++ b/documentation/src/main/asciidoc/querylanguage/Concepts.adoc @@ -489,7 +489,7 @@ But when there's no explicit `select` clause, the select list is implied by the List books = session.createQuery("from Book join authors", Book.class) .getResultList(); -for (Person person: persons) { +for (Book book: books) { ... } ---- @@ -546,6 +546,23 @@ HQL makes it very easy to fetch all the data we need in a single trip to the dat Typically, it's much worse to fetch exactly the data we need, but in many round trips to the database server, than it is to fetch just a bit more data than what we're going to need, all a single SQL query. ==== +When there's no explicit `select` clause, a further abbreviation is sometimes possible. + +[TIP] +==== +When the result type of a `select` query is an entity type, and we specify the type explicitly by passing the entity class to `createQuery()` or `createSelectionQuery()`, we're sometimes allowed to omit the `from` clause, for example: + +[source, java] +[%unbreakable] +---- +// explicit result type Book, so 'from Book' is inferred +List books = + session.createQuery("where title like :title", Book.class) + .setParameter("title", title) + .getResultList(); +---- +==== + [[returning-to-java]] === Representing result sets in Java diff --git a/documentation/src/main/asciidoc/querylanguage/extras/statement_select_bnf.txt b/documentation/src/main/asciidoc/querylanguage/extras/statement_select_bnf.txt index 307a276936..f517e53c71 100644 --- a/documentation/src/main/asciidoc/querylanguage/extras/statement_select_bnf.txt +++ b/documentation/src/main/asciidoc/querylanguage/extras/statement_select_bnf.txt @@ -10,6 +10,7 @@ orderedQuery query : selectClause fromClause? whereClause? (groupByClause havingClause?)? | fromClause whereClause? (groupByClause havingClause?)? selectClause? + | whereClause queryOrder : orderByClause limitClause? offsetClause? fetchClause?