Tutorial SpringBoot: API Query By Example (QBE)

Introducción

Spring Data JPA es un subproyecto de Spring Data que tiene como objetivo simplificar el acceso a datos en aplicaciones que usan tecnología de persistencia de datos.

Uno de sus aspectos más notables es Query By Example (QBE), una técnica de consulta de usuario fácil de usar que permite crear una consulta dinámica a partir de una entidad de instancia de ejemplo.

La técnica QBE funciona definiendo una instancia de objeto de una entidad, en la que los campos no nulos se utilizan para determinar los predicados de consulta. Con QBE, se puede crear una consulta dinámica utilizando las instancias de la entidad.

Para usar QBE en Spring, se necesita hacer uso del ExampleMatcher y Example.

Configuración de QBE en Spring

Primero, debe configurarse la interfaz de repositorio para usar QBE.

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.repository.query.QueryByExampleExecutor;

public interface UserRepository extends JpaRepository<User, Long>, QueryByExampleExecutor<User> {
}

Aquí, QueryByExampleExecutor es una interfaz de Spring Data que se puede extender para obtener funcionalidades QBE.

Uso básico de QBE

Un ejemplo simple de cómo usar QBE:

User user = new User();
user.setEmail("user@example.com");

Example<User> example = Example.of(user);

List<User> results = userRepository.findAll(example);

En este caso, se crea una nueva instancia de User y se establece el campo email. Luego, se usa este objeto User para crear un Example que se puede pasar al método findAll del repositorio. Este método devolverá todos los usuarios cuyos emails coincidan con "user@example.com".

Uso básico de QBE con múltiples campos

Si se tienen múltiples campos configurados en el objeto de muestra, todos se usarán en la consulta. Por ejemplo, supóngase una entidad User que tiene los campos firstName, lastName y email. Si se configuran todos estos campos en el objeto de muestra, la consulta resultante buscará usuarios que coincidan con todos estos campos.

User user = new User();
user.setFirstName("John");
user.setLastName("Doe");
user.setEmail("john.doe@example.com");

Example<User> example = Example.of(user);

List<User> results = userRepository.findAll(example);

En este caso, findAll(example) buscará usuarios cuyo firstName sea "John", cuyo lastName sea "Doe" y cuyo email sea "john.doe@example.com". Si un usuario coincide con todos estos campos, se incluirá en los resultados; si no coincide en uno o más campos, no se incluirá.

Uso avanzado de QBE

QBE también admite operaciones más complejas mediante el uso de un ExampleMatcher.

User user = new User();
user.setEmail("user");

ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("email", match -> match.startsWith())
  .withIgnorePaths("status");

Example<User> example = Example.of(user, matcher);

List<User> results = userRepository.findAll(example);

En este ejemplo, se ha configurado el ExampleMatcher para que el campo email haga coincidir al comienzo (startsWith), por lo que buscará usuarios cuyos emails comiencen con "user". También se ha configurado el ExampleMatcher para ignorar el campo status al realizar la coincidencia.

El objeto ExampleMatcher se puede utilizar para personalizar la forma en que se realizan las coincidencias en la consulta. Por defecto, todos los campos se comparan utilizando un igual estricto (equals). Sin embargo, puede cambiarse este comportamiento utilizando diferentes métodos en ExampleMatcher.

Hay dos formas de definir matchers en ExampleMatcher. Puede usarse una lambda como en match -> match.startsWith(), o puede usarse uno de los métodos estáticos en ExampleMatcher.GenericPropertyMatchers.

// Usando lambda
ExampleMatcher matcher1 = ExampleMatcher.matching()
  .withMatcher("email", match -> match.startsWith());

// Usando método estático
ExampleMatcher matcher2 = ExampleMatcher.matching()
  .withMatcher("email", ExampleMatcher.GenericPropertyMatchers.startsWith());

Ambos códigos hacen exactamente lo mismo: configuran el matcher para que el campo email en la consulta se haga coincidir al inicio. La diferencia es puramente sintáctica y puedes usarse cualquiera.

Creación de Queries personalizadas con QBE

QBE también permite la creación de consultas más personalizadas, según los diferentes tipos de condiciones que pueden necesitarse. Spring proporciona una serie de métodos que se pueden utilizar para personalizar las consultas, y estos pueden ser útiles para crear consultas más detalladas y precisas.

Configurando Matchers para campos específicos

ExampleMatcher proporciona métodos como withMatcher() que permiten configurar las coincidencias en los campos de la entidad. En el siguiente ejemplo, el método endsWith() se utiliza para hacer que el campo de email haga coincidir al final.

User user = new User();
user.setEmail("example.com");

ExampleMatcher matcher = ExampleMatcher.matching()
  .withMatcher("email", ExampleMatcher.GenericPropertyMatchers.endsWith());

Example<User> example = Example.of(user, matcher);

List<User> results = userRepository.findAll(example);

Aquí, findAll() devolverá todos los usuarios cuyos emails terminen en "example.com".

Ignorar la distinción entre mayúsculas y minúsculas

A veces, es posible que no desee distinguir entre mayúsculas y minúsculas al hacer coincidir. Se puede usar el método withIgnoreCase() para lograr esto.

User user = new User();
user.setEmail("USER");

ExampleMatcher matcher = ExampleMatcher.matching()
  .withIgnoreCase()
  .withMatcher("email", ExampleMatcher.GenericPropertyMatchers.startsWith());

Example<User> example = Example.of(user, matcher);

List<User> results = userRepository.findAll(example);

Aquí, findAll() devolverá todos los usuarios cuyos emails comiencen con "USER", sin tener en cuenta las mayúsculas y minúsculas.

Configuración de las propiedades a ignorar

El método withIgnorePaths() se puede utilizar para ignorar propiedades específicas durante la coincidencia. Esto puede ser útil si hay campos que no deben tenerse en cuenta en la consulta.

User user = new User();
user.setEmail("user@example.com");
user.setFirstName("John");

ExampleMatcher matcher = ExampleMatcher.matching()
  .withIgnorePaths("firstName");

Example<User> example = Example.of(user, matcher);

List<User> results = userRepository.findAll(example);

En este caso, la propiedad firstName se ignora durante la coincidencia, por lo que findAll() devolverá todos los usuarios con el email "user@example.com", independientemente de su firstName.

Estas son solo algunas de las muchas formas en las que QBE puede personalizarse para crear consultas más detalladas y precisas. Es una herramienta muy poderosa en Spring Data JPA que puede ayudar a simplificar y mejorar el proceso de consulta de datos.