Use cases of methods of QueryByExampleExecutor<T> interface in Spring data JPA

Question

What are the use cases of the methods of this interface QueryByExampleExecutor<T> in Spring data JPA. I have googled and found nothing more than the official documentation.

Perhaps someone can point me to the right resource with examples.

In particular, is findAll(Example<S> example, Pagable pageable) of that interface a simpler way to search, paginate, and sort?

Hereupon

Answer 1

The Spring Data JPA query-by-example technique uses Examples and ExampleMatchers to convert entity instances into the underlying query. The current official documentation has several useful examples. Here is my example inspired by documentation:

Person.java

public class Person {

  @Id
  private String id;
  private String firstname;
  private String lastname;
  private Address address;

  // … getters and setters omitted
}

PersonResource.java:

@RestController
@RequestMapping("/api")
public class PersonResource {

@GetMapping("/persons/{name}")
@Timed
public ResponseEntity<List<Person>> getPersons(@ApiParam Pageable pageable, @PathVariable String  name) {
    log.debug("REST request to get Person by : {}", name);
    Person person = new Person();                         
    person.setFirstname(name);  
    Page<Person> page = personRepository.findAll(Example.of(person), pageable);
    HttpHeaders headers = PaginationUtil.generatePaginationHttpHeaders(page, "/api/persons");
    return new ResponseEntity<>(page.getContent(), headers, HttpStatus.OK);
}

Posh

So why do we need to pass Example.of(person) and not person to findAll(). Can you please explain the reason of existence of Examples and ExampleMatcher? – Whimper

because QueryByExampleExecutor has this API. did you have a chance to read attached a link on official documentation? – Posh

Answer 2

From the Spring Docs for Example:

Support for query by example (QBE). An Example takes a probe to define the example. Matching options and type safety can be tuned using ExampleMatcher.

So this class and the QueryByExampleExecutor interface are part of Spring Data's implementation of this Query By Example paradigm.

From the Wikipedia post on Query by Example:

Query by Example (QBE) is a database query language for relational databases. It was devised by Moshé M. Zloof at IBM Research during the mid-1970s, in parallel to the development of SQL. It is the first graphical query language, using visual tables where the user would enter commands, example elements and conditions.

Finally, the documentation for the #findAll method that you reference states the following:

<S extends T> Page<S> findAll(Example<S> example, Pageable pageable)
Returns a Page of entities matching the given Example. In case no match could be found, an empty Page is returned.

So essentially QBE represents a way of querying a relational DB using a more natural, template-based querying syntax, as opposed to using SQL, and Spring Data has an API which supports that.

Padang

So It's safe to say example parameter in findAll(Example<S> example, Pageable pageable can provide some kind of filtering. I still haven't seen a tutorial or example on this. +1 for the Wikipedia link though. – Hereupon

@wiseOne Yep, it is a way of filtering. The Wikipedia link has a DB example, but if you click on the query-by-example StackOverflow tag there are some Spring examples too. – Padang