This is an automated email from the ASF dual-hosted git repository. jamesfredley pushed a commit to branch test/h7-functional-coverage in repository https://gitbox.apache.org/repos/asf/grails-core.git
commit 74bfe690efd9211d15452ed20494dbb62eec3e7e Author: James Fredley <[email protected]> AuthorDate: Thu Jun 11 14:09:44 2026 -0400 Document Hibernate 7 HQL query settings Assisted-by: Hephaestus:openai/gpt-5.5 --- .../docs/src/docs/asciidoc/querying/hql.adoc | 11 +++++++++-- grails-doc/src/en/ref/Domain Classes/executeQuery.adoc | 12 ++++++++++-- grails-doc/src/en/ref/Domain Classes/find.adoc | 2 +- grails-doc/src/en/ref/Domain Classes/findAll.adoc | 3 ++- 4 files changed, 22 insertions(+), 6 deletions(-) diff --git a/grails-data-hibernate7/docs/src/docs/asciidoc/querying/hql.adoc b/grails-data-hibernate7/docs/src/docs/asciidoc/querying/hql.adoc index 5d6a9c09c1..10678b813c 100644 --- a/grails-data-hibernate7/docs/src/docs/asciidoc/querying/hql.adoc +++ b/grails-data-hibernate7/docs/src/docs/asciidoc/querying/hql.adoc @@ -85,9 +85,9 @@ List results = Book.executeQuery( ['%Groovy%', 'Tech']) ---- -=== Pagination and Sorting +=== Query Settings -All `findAll` and `executeQuery` overloads accept a settings map as the last argument: +`find`, `findAll`, and `executeQuery` overloads accept a settings map as the last argument. Use it for pagination and Hibernate query settings such as `cache`, `readOnly`, `fetchSize`, `timeout`, `flushMode`, and `lock`: [source,groovy] ---- @@ -99,8 +99,15 @@ List results = Book.executeQuery( "from Book b where b.genre = :genre", [genre: 'Tech'], [max: 5, offset: 0, cache: true]) + +List locked = Book.findAll( + "from Book b where b.genre = :genre", + [genre: 'Tech'], + [lock: true]) ---- +When `lock: true` is used, GORM requests a pessimistic write lock and disables query caching for that query. + === Bulk Updates and Deletes [source,groovy] diff --git a/grails-doc/src/en/ref/Domain Classes/executeQuery.adoc b/grails-doc/src/en/ref/Domain Classes/executeQuery.adoc index f6c1cb1286..74e6d4f0c9 100644 --- a/grails-doc/src/en/ref/Domain Classes/executeQuery.adoc +++ b/grails-doc/src/en/ref/Domain Classes/executeQuery.adoc @@ -76,7 +76,15 @@ Account.executeQuery("select distinct a.number from Account a", // modify the FlushMode of the Query (default is `FlushMode.AUTO`) Account.executeQuery("select distinct a.number from Account a", - null, [flushMode: FlushMode.MANUAL]) + null, [flushMode: FlushMode.MANUAL]) + +// enable the query cache when Hibernate query caching is configured +Account.executeQuery("select distinct a.number from Account a", + null, [cache: true]) + +// request a pessimistic write lock; locked queries are not query-cacheable +Account.executeQuery("from Account a where a.branch = :branch", + [branch: 'London'], [lock: true]) ---- @@ -99,4 +107,4 @@ Parameters: * `query` - An HQL query * `positionalParams` - A `List` of parameters for a positional parameterized query * `namedParams` - A `Map` of named parameters for a named parameterized query -* `metaParams` - A `Map` of pagination parameters `max` or/and `offset`, as well as Hibernate query parameters `readOnly`, `fetchSize`, `timeout`, and `flushMode` +* `metaParams` - A `Map` of pagination parameters `max` and/or `offset`, as well as Hibernate query parameters `readOnly`, `fetchSize`, `timeout`, `flushMode`, `cache`, and `lock` diff --git a/grails-doc/src/en/ref/Domain Classes/find.adoc b/grails-doc/src/en/ref/Domain Classes/find.adoc index da7192da4d..220065de3b 100644 --- a/grails-doc/src/en/ref/Domain Classes/find.adoc +++ b/grails-doc/src/en/ref/Domain Classes/find.adoc @@ -78,5 +78,5 @@ Parameters: * `query` - An HQL query * `positionalParams` - A `List` of parameters for a positional parametrized HQL query * `namedParams` - A `Map` of named parameters a HQL query -* `queryParams` - A `Map` of query parameters. Currently, only `cache` is supported +* `queryParams` - A `Map` of query parameters such as `cache`, `readOnly`, `fetchSize`, `timeout`, `flushMode`, and `lock` * `example` - An instance of the domain class for query by example diff --git a/grails-doc/src/en/ref/Domain Classes/findAll.adoc b/grails-doc/src/en/ref/Domain Classes/findAll.adoc index 0e9ae24d44..7d7724fbda 100644 --- a/grails-doc/src/en/ref/Domain Classes/findAll.adoc +++ b/grails-doc/src/en/ref/Domain Classes/findAll.adoc @@ -119,9 +119,10 @@ Parameters: * `query` - An HQL query * `positionalParams` - A `List` of parameters for a positional parametrized HQL query * `namedParams` - A `Map` of named parameters a HQL query -* `queryParams` - A `Map` containing parameters 'max', and/or 'offset' and/or 'cache' +* `queryParams` - A `Map` containing parameters `max`, `offset`, `cache`, and other supported query settings * `example` - An instance of the domain class for query by example * `readOnly` - `true` if returned objects should not be automatically dirty-checked (simlar to `read()`) * `fetchSize` - number of rows fetched by the underlying JDBC driver per round trip * `flushMode` - Hibernate `FlushMode` override, defaults to `FlushMode.AUTO` * `timeout` - query timeout in seconds +* `lock` - `true` to request a pessimistic write lock; locked queries are not query-cacheable
