Tutorial SpringBoot: Consultas JPQL con @Query en Spring Data JPA

JPQL o Jakarta Persistence Query Language es una plataforma independiente de lenguaje de consulta orientada a objetos.

Se usa para hacer consultas contra entidades almacenadas en una base de datos relacional. Spring Data JPA utiliza JPQL para implementar consultas personalizadas y avanzadas. JPQL es similar en muchos aspectos a SQL, y se pueden hacer las mismas operaciones básicas, como SELECT, UPDATE, DELETE, JOIN, GROUP BY, ORDER BY, etc.

La principal diferencia es que JPQL permite una sintaxis orientada a objetos, lo que facilita la creación de consultas.

Cómo utilizar @Query con JPQL

En Spring Data JPA, se puede usar la anotación @Query para escribir consultas JPQL personalizadas.

El uso de la anotación @Query es bastante simple y directo. Simplemente, se escribe la consulta JPQL como un valor de la anotación @Query.

Por ejemplo, supóngase que se tiene una entidad Usuario:

@Entity
public class Usuario {
   @Id
   @GeneratedValue(strategy = GenerationType.IDENTITY)
   private Long id;

   private String nombre;
   private String email;
   private String ciudad;
   // getters y setters
}

Ahora, se crea un repositorio para la entidad Usuario. En este repositorio, se pueden definir las consultas JPQL personalizadas utilizando la anotación @Query.

public interface UsuarioRepositorio extends JpaRepository<Usuario, Long> {
   @Query("SELECT u FROM Usuario u WHERE u.ciudad = ?1")
   List<Usuario> findUsuariosByCiudad(String ciudad);
}

En este caso, se ha definido un método findUsuariosByCiudad que acepta un parámetro ciudad y devuelve una lista de usuarios que viven en esa ciudad. La consulta JPQL para este método se define en la anotación @Query.

Parámetros de Consulta

En el ejemplo anterior, se ha utilizado un parámetro posicional (?1) para representar el valor de entrada de la consulta. Este es el método más básico para pasar parámetros a una consulta JPQL.

Sin embargo, también pueden utilizarse parámetros con nombre para hacer que las consultas sean más legibles. Aquí hay un ejemplo de cómo se puede hacer esto:

public interface UsuarioRepositorio extends JpaRepository<Usuario, Long> {
   @Query("SELECT u FROM Usuario u WHERE u.ciudad = :ciudad")
   List<Usuario> findUsuariosByCiudad(@Param("ciudad") String ciudad);
}

En este caso, se ha reemplazado el parámetro posicional por uno con nombre (:ciudad) y hemos anotado el parámetro del método con @Param("ciudad"). Esto hace que nuestra consulta sea más legible, ya que ahora está claro que el parámetro del método ciudad se corresponde con el parámetro de la consulta ciudad.

Modificación de Consultas con @Modifying

Spring Data JPA también permite ejecutar consultas de actualización y borrado con la anotación @Query. Para hacer esto, es necesario marcar el método con la anotación @Modifying.

Aquí hay un ejemplo de cómo se puede hacer esto:

public interface UsuarioRepositorio extends JpaRepository<Usuario, Long> {
   @Modifying
   @Query("UPDATE Usuario u SET u.ciudad = :ciudad WHERE u.id = :id")
   int actualizarCiudadUsuario(@Param("id") Long id, @Param("ciudad") String ciudad);
}

En este caso, se ha definido un método actualizarCiudadUsuario que acepta dos parámetros id y ciudad y actualiza la ciudad de un usuario. La consulta JPQL para este método se define en la anotación @Query, y también se ha marcado este método con la anotación @Modifying para indicar que esta consulta modifica el estado de la base de datos.

Joins en JPQL

Al igual que SQL, JPQL ofrece soporte para operaciones de JOIN para combinar registros de dos o más tablas en una base de datos. Aquí hay un ejemplo de cómo se puede hacer esto:

public interface PedidoRepositorio extends JpaRepository<Pedido, Long> {
   @Query("SELECT p FROM Pedido p JOIN p.usuario u WHERE u.nombre = :nombre")
   List<Pedido> findPedidosPorNombreUsuario(@Param("nombre") String nombre);
}

En este ejemplo, Pedido es una entidad que tiene una asociación con la entidad Usuario. La consulta JPQL selecciona todos los pedidos que pertenecen a un usuario con un nombre específico.

Funciones de agregado

JPQL también admite funciones de agregado, que realizan una operación en un conjunto de valores para devolver un solo valor. Las funciones de agregado de JPQL incluyen COUNT(), AVG(), SUM(), MIN(), MAX(), y se pueden usar en la cláusula SELECT o HAVING de una consulta JPQL.

Aquí hay un ejemplo de cómo se puede usar la función COUNT():

public interface UsuarioRepositorio extends JpaRepository<Usuario, Long> {
   @Query("SELECT COUNT(u) FROM Usuario u WHERE u.ciudad = :ciudad")
   Long contarUsuariosPorCiudad(@Param("ciudad") String ciudad);
}

En este ejemplo, la consulta JPQL cuenta el número de usuarios que viven en una ciudad específica.

Subconsultas

JPQL también admite subconsultas, que son consultas que se incrustan en otras consultas. Se pueden usar en la cláusula WHERE o HAVING de una consulta JPQL.

Aquí hay un ejemplo de cómo se puede usar una subconsulta:

public interface UsuarioRepositorio extends JpaRepository<Usuario, Long> {
   @Query("SELECT u FROM Usuario u WHERE u.id IN (SELECT p.usuario.id FROM Pedido p WHERE p.total > :total)")
   List<Usuario> findUsuariosConPedidoMayorA(@Param("total") BigDecimal total);
}

En este ejemplo, la consulta JPQL selecciona los usuarios que han realizado un pedido con un total mayor a un valor específico.

Consultas nativas

Spring Data JPA permite la ejecución de consultas nativas mediante el uso de la anotación @Query con el atributo nativeQuery = true.

Esto puede ser útil en situaciones donde JPQL no pueda satisfacer las necesidades de consulta o cuando se quiera hacer uso de características específicas de la base de datos subyacente que no están disponibles en JPQL.

Aquí hay un ejemplo breve de cómo se puede usar una consulta nativa:

public interface UsuarioRepositorio extends JpaRepository<Usuario, Long> {
   @Query(value = "SELECT * FROM usuarios WHERE ciudad = :ciudad", nativeQuery = true)
   List<Usuario> findUsuariosByCiudad(@Param("ciudad") String ciudad);
}

En este ejemplo, se ejecuta una consulta SQL nativa que selecciona todos los usuarios de una ciudad específica.

Es importante tener en cuenta que el uso de consultas nativas puede hacer que la aplicación sea menos portable, ya que se están escribiendo consultas que son específicas para una base de datos y no funcionarán necesariamente en otro tipo de bases de datos.

Además, debe tenerse cuidado con la inyección de SQL al usar consultas nativas, asegurándose de que los valores de los parámetros de las consultas no sean manipulados por los usuarios para prevenir la inyección de SQL.