Spring/spring-data-commons
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add documentation for the fluent API for Query By Example.

Browse Source 
Closes #2654
Original pull request #2655
See #2228
This commit is contained in:
Jens Schauder
2022-07-13 15:19:20 +02:00
parent 74e52612bf
commit b1aeec1576
1 changed files with 32 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
src/main/asciidoc/query-by-example.adoc
View File

@@ -13,13 +13,15 @@ In fact, Query by Example does not require you to write queries by using store-s
[[query-by-example.usage]]
== Usage
The Query by Example API consists of three parts:
The Query by Example API consists of four parts:
* Probe: The actual example of a domain object with populated fields.
* `ExampleMatcher`: The `ExampleMatcher` carries details on how to match particular fields.
It can be reused across multiple Examples.
* `Example`: An `Example` consists of the probe and the `ExampleMatcher`.
It is used to create the query.
* `FetchableFluentQuery`: A `FetchableFluentQuery` offers a fluent API, that allows further customization of a query derived from an `Example`.
Using the fluent API allows you to specify ordering, projection and result processing for your query.
Query by Example is well suited for several use cases:
@@ -56,7 +58,8 @@ The preceding example shows a simple domain object.
You can use it to create an `Example`.
By default, fields having `null` values are ignored, and strings are matched by using the store specific defaults.
NOTE: Inclusion of properties into a Query by Example criteria is based on nullability. Properties using primitive types (`int`, `double`, …) are always included unless <<query-by-example.matchers,ignoring the property path>>.
NOTE: Inclusion of properties into a Query by Example criteria is based on nullability.
Properties using primitive types (`int`, `double`, …) are always included unless <<query-by-example.matchers,ignoring the property path>>.
Examples can be built by either using the `of` factory method or by using <<query-by-example.matchers,`ExampleMatcher`>>. `Example` is immutable.
The following listing shows a simple Example:
@@ -70,6 +73,7 @@ person.setFirstname("Dave"); <2>
Example<Person> example = Example.of(person); <3>
----
<1> Create a new instance of the domain object.
<2> Set the properties to query.
<3> Create the `Example`.
@@ -115,6 +119,7 @@ ExampleMatcher matcher = ExampleMatcher.matching() <3>
Example<Person> example = Example.of(person, matcher); <7>
----
<1> Create a new instance of the domain object.
<2> Set properties.
<3> Create an `ExampleMatcher` to expect all values to match.
@@ -186,3 +191,28 @@ The following table describes the scope of the various `ExampleMatcher` settings
| Property path
|===
[[query-by-example.fluent]]
== Fluent API
`QueryByExampleExecutor` offers one more method, which we did not mention so far: `<S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction)`.
As with other methods it executes a query derived from an `Example`.
But with the second argument you can control aspects of that execution, that you can't control dynamically otherwise.
You do so by invoking the various methods of the `FetchableFluentQuery` in the second argument.
`sortBy` allows you to specify an ordering for your result.
`as` allows you to specify the type to which you want the result to be transformed.
`project` limits the attributes queried.
`first`, `firstValue`, `one`, `oneValue`, `all`, `page`, `stream`, `count`, `exists` define what kind of result you'll get and also how the query behaves when more than the expected number of results are available.
.Use the fluent API to get the last of potentially many results, ordered by lastname.
====
[source,java]
----
Optional<Person> match = repository.findBy(example,
q -> q
.sortBy(Sort.by("lastname").descending())
.first()
);
----
====