diff --git a/src/main/asciidoc/repositories.adoc b/src/main/asciidoc/repositories.adoc index b95c5c199..a7bf54efb 100644 --- a/src/main/asciidoc/repositories.adoc +++ b/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 { @@ -368,13 +370,28 @@ interface PersonRepository extends Repository { ---- ==== -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 <>. -- 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 appendix contains the <> and <>. +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 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 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: -- 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 "`<>`". +- 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. + +- 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.query-methods.query-property-expressions]] === Property Expressions @@ -496,7 +513,8 @@ List 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 <>. [[repositories.collections-and-iterables.streamable]] ==== Using Streamable as Query Method Return Type diff --git a/src/main/asciidoc/repository-query-keywords-reference.adoc b/src/main/asciidoc/repository-query-keywords-reference.adoc index 49b07aa1c..70a09f0e9 100644 --- a/src/main/asciidoc/repository-query-keywords-reference.adoc +++ b/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…`, `…Top…`| Limit the query results to the first `` 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`). +|=============== diff --git a/src/main/asciidoc/repository-query-return-types-reference.adoc b/src/main/asciidoc/repository-query-return-types-reference.adoc index 9b03f43d1..730f777d1 100644 --- a/src/main/asciidoc/repository-query-return-types-reference.adoc +++ b/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`|A `Future`. Expects a method to be annotated with `@Async` and requires Spring's asynchronous method execution capability to be enabled. |`CompletableFuture`|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`|A sized chunk of data with an indication of whether there is more data available. Requires a `Pageable` method parameter. |`Page`|A `Slice` with additional information, such as the total number of results. Requires a `Pageable` method parameter. |`GeoResult`|A result entry with additional information, such as the distance to a reference location. |`GeoResults`|A list of `GeoResult` with additional information, such as the average distance to a reference location.