////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////


== findAll



=== Purpose


Finds all of domain class instances matching the specified query


=== Examples


[source,groovy]
----
// everything
Book.findAll()

// with a positional parameter
Book.findAll("from Book as b where b.author=?", ['Dan Brown'])

// 10 books from Dan Brown staring from 5th book ordered by release date
Book.findAll("from Book as b where b.author=? order by b.releaseDate",
             ['Dan Brown'], [max: 10, offset: 5])

// examples with max/offset usage
def query = "from Book as b where b.author='Dan Brown' order by b.releaseDate"

// first 10 books
Book.findAll(query, [max: 10])

// 10 books starting from 5th
Book.findAll(query, [max: 10, offset: 5])

// examples with named parameters
Book.findAll("from Book as b where b.author=:author",
             [author: 'Dan Brown'])
Book.findAll("from Book as b where b.author=:author",
             [author: 'Dan Brown'], [max: 10, offset: 5])
Book.findAll("from Book as b where b.author in (:authors)",
             [authors: ['Dan Brown', 'Jack London']])

// examples with tables join
Book.findAll("from Book as b where not exists " +
                "(from Borrow as br where br.book = b)")

// query by example
def example = new Book(author: "Dan Brown")
Book.findAll(example)

// Use where criteria (since Grails 2.0)
def results = Person.findAll {
     lastName == "Simpson"
}
def results = Person.findAll(sort:"firstName") {
     lastName == "Simpson"
}
----


=== Description


The `findAll` method allows querying with Hibernate's query language  link:{hibernate5GuideFromRef}index.html#hql[HQL] and querying by example, returning all matching instances. Pagination can be controlled using the `max` and `offset` parameters:

[source,groovy]
----
Book.findAll("from Book as b where b.author=:author",
             [author: 'Dan Brown'], [max: 10, offset: 5])
----

The `findAll` method supports the 2nd level cache:

[source,groovy]
----
Book.findAll("from Book as b where b.author=:author",
             [author:'Dan Brown'], [max: 10, offset: 5, cache: true])
----

The basic syntax for the method is:

[source,groovy]
----
Book.findAll()
Book.findAll(String query)
Book.findAll(String query, Collection positionalParams)
Book.findAll(String query, Collection positionalParams, Map queryParams)
Book.findAll(String query, Map namedParams)
Book.findAll(String query, Map namedParams, Map queryParams)
Book.findAll(Book example)
Book.findAll(Closure whereCriteria)
Book.findAll(Map queryParams, Closure whereCriteria)
----

NOTE: If you have a join in your HQL, the method will return a `List` of `Array`s containing domain class instances. You may wish to use link:executeQuery.html[executeQuery] in this case so you have more flexibility in specifying what gets returned.

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`, `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
