Crear consultas personalizadas en Spring Boot no siempre requiere escribir sentencias SQL o JPQL. Los query methods permiten definir búsquedas directamente en el nombre del método dentro de un repositorio, y Spring se encarga de interpretar la lógica automáticamente. Esta funcionalidad simplifica el acceso a datos y reduce el código repetitivo en cualquier proyecto.
¿Qué es un query method y cómo funciona?
Un query method es un método declarado en una interfaz que extiende de JpaRepository. Su nombre sigue una convención específica que Spring Boot interpreta para generar la consulta correspondiente a nivel de base de datos [0:30]. No necesitas escribir la implementación: solo defines la firma del método y Spring hace el resto.
Por ejemplo, si tu interfaz UserRepository hereda de JpaRepository, puedes declarar métodos como:
findByLastName(String lastName): retorna una lista de usuarios filtrados por apellido.findByEmailAddress(String emailAddress): retorna un único usuario a partir de su dirección de email.
Cada query method responde a una necesidad puntual: recibe parámetros de entrada y retorna un resultado acorde, ya sea una lista o un objeto individual [1:05].
¿Cómo crear un query method paso a paso?
Dentro del repositorio UserRepository, se define el método siguiendo la convención findBy más el nombre del atributo de la entidad [1:30]. Por ejemplo:
java
List<User> findByName(String name);
Este método busca todos los usuarios cuyo nombre coincida con el parámetro recibido. Al retornar una lista, contempla la posibilidad de que existan múltiples registros con el mismo nombre.
¿Cómo se invoca desde la aplicación principal?
En la clase FundamentosApplication, se llama al repositorio y se ejecuta el query method [1:50]:
java
userRepository.findByName("John")
.stream()
.forEach(user -> logger.info("Usuario con query method: " + user));
Al ejecutar la aplicación, el resultado muestra cada usuario que coincida con el nombre "John". Si hay varios registros con ese nombre, todos aparecen en el listado [2:45].
¿Cómo buscar por múltiples parámetros?
Se pueden combinar atributos usando la palabra clave And en el nombre del método [3:15]. Esto genera una consulta con múltiples condiciones:
java
Optional<User> findByEmailAndName(String email, String name);
Aquí el tipo de retorno cambia a Optional<User>, lo cual permite un manejo seguro de valores nulos. Si no se encuentra el usuario, se puede lanzar una excepción controlada [3:50]:
java
userRepository.findByEmailAndName("daniela@domain", "Daniela")
.orElseThrow(() -> new RuntimeException("Usuario no encontrado"));
¿Qué diferencias existen entre query methods y JPQL?
Los query methods son una alternativa directa a las anotaciones @Query con JPQL [4:40]. Mientras que JPQL requiere escribir la consulta como una cadena dentro de la anotación, los query methods expresan la lógica en el propio nombre del método.
Algunas diferencias importantes:
- Simplicidad: los query methods no requieren escribir consultas explícitas.
- Flexibilidad en retorno: puedes devolver listas, objetos únicos u
Optional según la necesidad.
- Múltiples parámetros: puedes combinar condiciones con
And, Or, Between, OrderBy y Sort.
- Legibilidad: el nombre del método describe exactamente qué hace la consulta.
El uso de Optional como tipo de retorno es especialmente útil cuando se espera un solo resultado, ya que evita excepciones de tipo NullPointerException y permite manejar el caso de "no encontrado" con orElseThrow [3:55].
La convención de nombrado es clave: Spring analiza el prefijo findBy, identifica los atributos de la entidad y construye la consulta SQL automáticamente. Esto significa que si el atributo no existe en la entidad, la aplicación lanzará un error al iniciar.
Si quieres ampliar tus consultas con operadores como Or, OrderBy o Between, comparte en los comentarios qué combinaciones te resultan más útiles en tus proyectos.
