Documentation for Query By Example.

Original pull request #1195
See #1192

Author: schauder

src/main/asciidoc/jdbc.adoc

@@ -700,6 +700,9 @@ You can specify the following return types:
 * `int` (updated record count)
 * `boolean`(whether a record was updated)
 
+include::{spring-data-commons-docs}/query-by-example.adoc[leveloffset=+1]
+include::query-by-example.adoc[leveloffset=+1]
+
 include::{spring-data-commons-docs}/repository-projections.adoc[leveloffset=+2]
 
 [[jdbc.mybatis]]

src/main/asciidoc/query-by-example.adoc

@@ -0,0 +1,67 @@
+[[query-by-example.running]]
+== Running an Example
+
+In Spring Data JDBC, you can use Query by Example with Repositories, as shown in the following example:
+
+.Query by Example using a Repository
+====
+[source, java]
+----
+public interface PersonRepository
+        extends CrudRepository<Person, String>,
+        QueryByExampleExecutor<Person> { … }
+
+public class PersonService {
+
+  @Autowired PersonRepository personRepository;
+
+  public List<Person> findPeople(Person probe) {
+    return personRepository.findAll(Example.of(probe));
+  }
+}
+----
+====
+
+NOTE: Currently, only `SingularAttribute` properties can be used for property matching.
+
+The property specifier accepts property names (such as `firstname` and `lastname`). You can navigate by chaining properties together with dots (`address.city`). You can also tune it with matching options and case sensitivity.
+
+The following table shows the various `StringMatcher` options that you can use and the result of using them on a field named `firstname`:
+
+[cols="1,2", options="header"]
+.`StringMatcher` options
+|===
+| Matching
+| Logical result
+
+| `DEFAULT` (case-sensitive)
+| `firstname = ?0`
+
+| `DEFAULT` (case-insensitive)
+| `LOWER(firstname) = LOWER(?0)`
+
+| `EXACT`  (case-sensitive)
+| `firstname = ?0`
+
+| `EXACT` (case-insensitive)
+| `LOWER(firstname) = LOWER(?0)`
+
+| `STARTING`  (case-sensitive)
+| `firstname like ?0 + '%'`
+
+| `STARTING` (case-insensitive)
+| `LOWER(firstname) like LOWER(?0) + '%'`
+
+| `ENDING`  (case-sensitive)
+| `firstname like '%' + ?0`
+
+| `ENDING` (case-insensitive)
+| `LOWER(firstname) like '%' + LOWER(?0)`
+
+| `CONTAINING`  (case-sensitive)
+| `firstname like '%' + ?0 + '%'`
+
+| `CONTAINING` (case-insensitive)
+| `LOWER(firstname) like '%' + LOWER(?0) + '%'`
+
+|===