From 40ba0271116d54a53c265bf212bde0b8e5a826d8 Mon Sep 17 00:00:00 2001 From: Thomas Darimont Date: Fri, 17 Oct 2014 19:01:26 +0200 Subject: [PATCH 1/2] DATACMNS-580 - Add section on limiting the query results to reference documentation. Prepare issue branch. --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 44b1e51deb..24ecb5e793 100644 --- a/pom.xml +++ b/pom.xml @@ -5,7 +5,7 @@ org.springframework.data spring-data-commons - 1.10.0.BUILD-SNAPSHOT + 1.10.0.DATACMNS-580-SNAPSHOT Spring Data Core From 3f54bcdbddba4c502ed0f8d1ffc07ed191d45de7 Mon Sep 17 00:00:00 2001 From: Thomas Darimont Date: Fri, 17 Oct 2014 19:02:17 +0200 Subject: [PATCH 2/2] DATACMNS-580 - Add section on limiting the query results to reference documentation. Added section explaining the use of first / top keywords to the reference doc. Updated the keyword list. Original pull request: #99. --- src/main/asciidoc/repositories.adoc | 32 ++++++++++++++++++- .../repository-query-keywords-reference.adoc | 2 ++ 2 files changed, 33 insertions(+), 1 deletion(-) diff --git a/src/main/asciidoc/repositories.adoc b/src/main/asciidoc/repositories.adoc index 37e1077e52..655322e6e9 100644 --- a/src/main/asciidoc/repositories.adoc +++ b/src/main/asciidoc/repositories.adoc @@ -296,12 +296,42 @@ List findByLastname(String lastname, Pageable pageable); ---- ==== -The first method allows you to pass an `org.springframework.data.domain.Pageable` instance to the query method to dynamically add paging to your statically defined query. A `Page` knows about the total number of elements and pages available. It does so by the infrastructure triggering a count query to calculate the overall number. As this might be expensive depending on the store used, `Slice` can be used as return instead. A `Slice` only knows about whether there's a next `Slice` available which might be just sufficient when walking thought a larger resut set. +The first method allows you to pass an `org.springframework.data.domain.Pageable` instance to the query method to dynamically add paging to your statically defined query. A `Page` knows about the total number of elements and pages available. It does so by the infrastructure triggering a count query to calculate the overall number. As this might be expensive depending on the store used, `Slice` can be used as return instead. A `Slice` only knows about whether there's a next `Slice` available which might be just sufficient when walking thought a larger result set. Sorting options are handled through the `Pageable` instance too. If you only need sorting, simply add an `org.springframework.data.domain.Sort` parameter to your method. As you also can see, simply returning a `List` is possible as well. In this case the additional metadata required to build the actual `Page` instance will not be created (which in turn means that the additional count query that would have been necessary not being issued) but rather simply restricts the query to look up only the given range of entities. NOTE: To find out how many pages you get for a query entirely you have to trigger an additional count query. By default this query will be derived from the query you actually trigger. +[[repositories.limit-query-result]] +=== Limiting query results + +The results of query methods can be limited via the keywords `first` or `top`, which can be used interchangeably. An optional numeric value can be appended to top/first to specify the maximum result size to be returned. +If the number is left out, a result size of 1 is assumed. + +.Limiting the result size of a query with `Top` and `First` +==== +[source, java] +---- +User findFirstByOrderByLastname(); + +User findTopByOrderByAgeDesc(); + +Page queryFirst10ByLastname(String lastname, Pageable pageable); + +Slice findTop3ByLastname(String lastname, Pageable pageable); + +List findFirst10ByLastname(String lastname, Sort sort); + +List findTop10ByLastname(String lastname, Pageable pageable); +---- +==== + +The limiting expressions also support the `Distinct` keyword. Also, for the queries limiting the result set to one instance, wrapping the result into an `Optional` is supported. + +If pagination or slicing is applied to a limiting query pagination (and the calculation of the number of pages available) then it is applied within the limited result. + +NOTE: Note that limiting the results in combination with dynamic sorting via a `Sort` parameter allows to express query methods for the 'K' smallest as well as for the 'K' biggest elements. + [[repositories.create-instances]] == Creating repository instances In this section you create instances and bean definitions for the repository interfaces defined. One way to do so is using the Spring namespace that is shipped with each Spring Data module that supports the repository mechanism although we generally recommend to use the Java-Config style configuration. diff --git a/src/main/asciidoc/repository-query-keywords-reference.adoc b/src/main/asciidoc/repository-query-keywords-reference.adoc index 0e16bd5729..170b9bcd6d 100644 --- a/src/main/asciidoc/repository-query-keywords-reference.adoc +++ b/src/main/asciidoc/repository-query-keywords-reference.adoc @@ -35,5 +35,7 @@ The following table lists the keywords generally supported by the Spring Data re |`STARTING_WITH`|`StartingWith`, `IsStartingWith`, `StartsWith` |`TRUE`|`True`, `IsTrue` |`WITHIN`|`Within`, `IsWithin` +|`TOP`|`Top` +|`FIRST`|`First` |===============