DATACMNS-1833 - Revise documentation for query method keywords.

Original pull request: #477.

Author: mp911de

src/main/asciidoc/repositories.adoc

@@ -342,11 +342,13 @@ The following strategies are available for the repository infrastructure to reso
 [[repositories.query-methods.query-creation]]
 === Query Creation
 
-The query builder mechanism built into the Spring Data repository infrastructure is useful for building constraining queries over entities of the repository. The mechanism strips the `find…By`, `read…By`, `query…By`, `count…By`, and `get…By` prefixes from the method and starts parsing the rest of it. The introducing clause can contain further expressions, such as a `Distinct` to set a distinct flag on the query to be created. However, the first `By` acts as a delimiter to indicate the start of the actual criteria. At a very basic level, you can define conditions on entity properties and concatenate them with `And` and `Or`. The following example shows how to create a number of queries:
+The query builder mechanism built into the Spring Data repository infrastructure is useful for building constraining queries over entities of the repository.
+
+The following example shows how to create a number of queries:
 
 .Query creation from method names
 ====
-[source, java]
+[source,java]
 ----
 interface PersonRepository extends Repository<Person, Long> {
 
@@ -368,13 +370,28 @@ interface PersonRepository extends Repository<Person, Long> {
 ----
 ====
 
-The actual result of parsing the method depends on the persistence store for which you create the query. However, there are some general things to notice:
+Parsing query method names is divided into subject and predicate.
+The first part (`find…By`, `exists…By`) defines the subject of the query, the second part forms the predicate.
+The introducing clause (subject) can contain further expressions.
+Any text between `find` (or other introducing keywords) and `By` is considered to be descriptive unless using one of the result-limiting keywords such as a `Distinct` to set a distinct flag on the query to be created or <<repositories.limit-query-result,`Top`/`First` to limit query results>>.
+
+The appendix contains the <<appendix.query.method.subject,full list of query method subject keywords>> and <<appendix.query.method.predicate,query method predicate keywords including sorting and letter-casing modifiers>>.
+However, the first `By` acts as a delimiter to indicate the start of the actual criteria predicate.
+At a very basic level, you can define conditions on entity properties and concatenate them with `And` and `Or`.
+
+The actual result of parsing the method depends on the persistence store for which you create the query.
+However, there are some general things to notice:
 
-- The expressions are usually property traversals combined with operators that can be concatenated. You can combine property expressions with `AND` and `OR`. You also get support for operators such as `Between`, `LessThan`, `GreaterThan`, and `Like` for the property expressions. The supported operators can vary by datastore, so consult the appropriate part of your reference documentation.
+- The expressions are usually property traversals combined with operators that can be concatenated.
+You can combine property expressions with `AND` and `OR`.
+You also get support for operators such as `Between`, `LessThan`, `GreaterThan`, and `Like` for the property expressions.
+The supported operators can vary by datastore, so consult the appropriate part of your reference documentation.
 
-- The method parser supports setting an `IgnoreCase` flag for individual properties (for example, `findByLastnameIgnoreCase(…)`) or for all properties of a type that supports ignoring case (usually `String` instances -- for example, `findByLastnameAndFirstnameAllIgnoreCase(…)`). Whether ignoring cases is supported may vary by store, so consult the relevant sections in the reference documentation for the store-specific query method.
+- The method parser supports setting an `IgnoreCase` flag for individual properties (for example, `findByLastnameIgnoreCase(…)`) or for all properties of a type that supports ignoring case (usually `String` instances -- for example, `findByLastnameAndFirstnameAllIgnoreCase(…)`).
+Whether ignoring cases is supported may vary by store, so consult the relevant sections in the reference documentation for the store-specific query method.
 
-- You can apply static ordering by appending an `OrderBy` clause to the query method that references a property and by providing a sorting direction (`Asc` or `Desc`). To create a query method that supports dynamic sorting, see "`<<repositories.special-parameters>>`".
+- You can apply static ordering by appending an `OrderBy` clause to the query method that references a property and by providing a sorting direction (`Asc` or `Desc`).
+To create a query method that supports dynamic sorting, see "`<<repositories.special-parameters>>`".
 
 [[repositories.query-methods.query-property-expressions]]
 === Property Expressions
@@ -496,7 +513,8 @@ List<User> findTop10ByLastname(String lastname, Pageable pageable);
 ----
 ====
 
-The limiting expressions also support the `Distinct` keyword. Also, for the queries that limit the result set to one instance, wrapping the result into with the `Optional` keyword is supported.
+The limiting expressions also support the `Distinct` keyword for datastores that support distinct queries.
+Also, for the queries that limit the result set to one instance, wrapping the result into with the `Optional` keyword is supported.
 
 If pagination or slicing is applied to a limiting query pagination (and the calculation of the number of available pages), it is applied within the limited result.
 
@@ -507,6 +525,7 @@ NOTE: Limiting the results in combination with dynamic sorting by using a `Sort`
 
 Query methods that return multiple results can use standard Java `Iterable`, `List`, and `Set`.
 Beyond that, we support returning Spring Data's `Streamable`, a custom extension of `Iterable`, as well as collection types provided by https://www.vavr.io/[Vavr].
+Refer to the appendix explaining all possible <<appendix.query.return.types,query method return types>>.
 
 [[repositories.collections-and-iterables.streamable]]
 ==== Using Streamable as Query Method Return Type

src/main/asciidoc/repository-query-keywords-reference.adoc

@@ -2,11 +2,32 @@
 [appendix]
 = Repository query keywords
 
-== Supported query keywords
-The following table lists the keywords generally supported by the Spring Data repository query derivation mechanism. However, consult the store-specific documentation for the exact list of supported keywords, because some keywords listed here might not be supported in a particular store.
+[[appendix.query.method.subject]]
+== Supported query method subject keywords
 
-.Query keywords
-[options="header", cols="1,3"]
+The following table lists the subject keywords generally supported by the Spring Data repository query derivation mechanism to express the predicate.
+Consult the store-specific documentation for the exact list of supported keywords, because some keywords listed here might not be supported in a particular store.
+
+.Query subject keywords
+[options="header",cols="1,3"]
+|===============
+|Keyword | Description
+|`find…By`, `read…By`, `get…By`, `query…By`, `search…By`, `stream…By`| General query method returning typically the repository type, a `Collection` or `Streamable` subtype or a result wrapper such as `Page`, `GeoResults` or any other store-specific result wrapper. Can be used as `findBy…`, `findMyDomainTypeBy…` or in combination with additional keywords.
+|`exists…By`| Exists projection, returning typically a `boolean` result.
+|`count…By`| Count projection returning a numeric result.
+|`delete…By`, `remove…By`| Delete query method returning either no result (`void`) or the delete count.
+|`…First<number>…`, `…Top<number>…`| Limit the query results to the first `<number>` of results. This keyword can occur in any place of the subject between `find` (and the other keywords) and `by`.
+|`…Distinct…`| Use a distinct query to return only unique results. Consult the store-specific documentation whether that feature is supported. This keyword can occur in any place of the subject between `find` (and the other keywords) and `by`.
+|===============
+
+[[appendix.query.method.predicate]]
+== Supported query method predicate keywords and modifiers
+
+The following table lists the predicate keywords generally supported by the Spring Data repository query derivation mechanism.
+However, consult the store-specific documentation for the exact list of supported keywords, because some keywords listed here might not be supported in a particular store.
+
+.Query predicate keywords
+[options="header",cols="1,3"]
 |===============
 |Logical keyword|Keyword expressions
 |`AND`|`And`
@@ -38,3 +59,14 @@ The following table lists the keywords generally supported by the Spring Data re
 |`TRUE`|`True`, `IsTrue`
 |`WITHIN`|`Within`, `IsWithin`
 |===============
+
+In addition to filter predicates, the following list of modifiers is supported:
+
+.Query predicate modifier keywords
+[options="header",cols="1,3"]
+|===============
+|Keyword | Description
+|`IgnoreCase`, `IgnoringCase`| Used with a predicate keyword for case-insensitive comparison.
+|`AllIgnoreCase`, `AllIgnoringCase`| Ignore case for all suitable properties. Used somewhere in the query method predicate.
+|`OrderBy…`| Specify a static sorting order followed by the property path and direction (e. g. `OrderByFirstnameAscLastnameDesc`).
+|===============

src/main/asciidoc/repository-query-return-types-reference.adoc

@@ -2,13 +2,17 @@
 [[repository-query-return-types]]
 = Repository query return types
 
+[[appendix.query.return.types]]
 == Supported Query Return Types
-The following table lists the return types generally supported by Spring Data repositories. However, consult the store-specific documentation for the exact list of supported return types, because some types listed here might not be supported in a particular store.
+
+The following table lists the return types generally supported by Spring Data repositories.
+However, consult the store-specific documentation for the exact list of supported return types, because some types listed here might not be supported in a particular store.
 
 NOTE: Geospatial types (such as `GeoResult`, `GeoResults`, and `GeoPage`) are available only for data stores that support geospatial queries.
+Some store modules may define their own result wrapper types.
 
 .Query return types
-[options="header", cols="1,3"]
+[options="header",cols="1,3"]
 |===============
 |Return type|Description
 |`void`|Denotes no return value.
@@ -27,7 +31,7 @@ NOTE: Geospatial types (such as `GeoResult`, `GeoResults`, and `GeoPage`) are av
 |`Future<T>`|A `Future`. Expects a method to be annotated with `@Async` and requires Spring's asynchronous method execution capability to be enabled.
 |`CompletableFuture<T>`|A Java 8 `CompletableFuture`. Expects a method to be annotated with `@Async` and requires Spring's asynchronous method execution capability to be enabled.
 |`ListenableFuture`|A `org.springframework.util.concurrent.ListenableFuture`. Expects a method to be annotated with `@Async` and requires Spring's asynchronous method execution capability to be enabled.
-|`Slice`|A sized chunk of data with an indication of whether there is more data available. Requires a `Pageable` method parameter.
+|`Slice<T>`|A sized chunk of data with an indication of whether there is more data available. Requires a `Pageable` method parameter.
 |`Page<T>`|A `Slice` with additional information, such as the total number of results. Requires a `Pageable` method parameter.
 |`GeoResult<T>`|A result entry with additional information, such as the distance to a reference location.
 |`GeoResults<T>`|A list of `GeoResult<T>` with additional information, such as the average distance to a reference location.