Los query methods de Spring Data JPA permiten limitar la cantidad de registros que recuperas de la base de datos y combinarlos con elementos de programación funcional como Optional. Si trabajas con repositorios JPA y quieres consultas más precisas, aquí ves cómo aplicarlo en una API de pizzería paso a paso.

Cómo limitar resultados con findFirst y findTop en Spring Data JPA

Cuando una consulta debe devolver un único registro, no necesitas traer toda la lista y quedarte con el primero. Spring Data JPA ofrece dos palabras clave que resuelven esto en el nombre del método: findFirst y findTop.

Ambas hacen lo mismo: limitan la consulta a un solo resultado. La diferencia es estilística, así que puedes usar la que te resulte más legible. Por ejemplo, partiendo de un método que recuperaba pizzas por nombre, basta con cambiar la firma a findFirstBy... para asegurar que solo regresa un registro [01:08].

¿Qué diferencia hay entre findFirst y findTop? Ninguna funcional. Ambos limitan el resultado a un solo registro o al número que indiques (por ejemplo, findTop3). Spring traduce ambos al keyword propio de la base de datos, como LIMIT en MySQL.

Al revisar la consola, verás que Spring convierte ese método a SQL agregando LIMIT 1 automáticamente cuando la base de datos es MySQL. Cada motor tiene su propia regla, pero el repositorio se encarga de la traducción.

Por qué conviene retornar Optional en un query method

Retornar Optional<PizzaEntity> te permite manejar la ausencia de resultados con las herramientas de programación funcional que ofrece Java, en lugar de validar null manualmente.

Desde el servicio puedes encadenar dos métodos muy útiles:

• orElse: devuelve un valor por defecto, como null u otra entidad, cuando no hay resultado.
• orElseThrow: lanza una excepción cuando la consulta no encuentra nada, por ejemplo new RuntimeException("La pizza no existe") [02:30].

Esto cambia el comportamiento de tu API. Si consultas una pizza con nombre Popeye y existe, recibes la entidad. Si la consultas como Popeyes y no existe, obtienes un error 500 con la excepción registrada en consola. Así integras Optional con los query methods sin escribir lógica adicional.

Cómo traer los registros más baratos con findTop3 y orderBy

Los query methods también permiten traer un número fijo de registros ordenados por un criterio. Imagina que necesitas mostrar las tres pizzas más baratas por debajo de cierto precio.

En el repositorio, defines el método así:

java List<PizzaEntity> findTop3ByAvailableTrueAndPriceLessThanEqualOrderByPriceAsc(double price);

Cada parte del nombre cumple un rol:

• findTop3By: limita el resultado a tres registros.
• AvailableTrue: filtra solo las pizzas disponibles.
• AndPriceLessThanEqual: aplica el filtro de precio máximo recibido como parámetro.
• OrderByPriceAsc: ordena el resultado de menor a mayor; con Desc sería al revés.

¿Qué hace lessThanEqual en un query method? Es el operador que traduce a <= en SQL. Lo usas cuando quieres incluir el valor límite en la consulta, como precios menores o iguales a 20 dólares.

Luego, en la capa de servicio creas un método getCheapest(double price) que llama al repositorio, y en el controlador expones un endpoint con @PathVariable para recibir el precio. Por ejemplo, al consultar cheapest/21, la API devuelve tres pizzas con precios de 18.5, 18.95 y 19.5 dólares, ordenadas ascendentemente [05:55].

Cómo se traduce el query method a SQL en la consola

Al revisar el log de Hibernate, verás la consulta generada: selecciona de la tabla pizza, aplica WHERE available = true AND price <= ?, ordena por precio ascendente y limita el resultado con LIMIT 3. Spring reemplaza el número que pusiste en findTop3 directamente en la cláusula LIMIT.

Esto te da una forma declarativa de armar consultas complejas sin escribir SQL ni JPQL. Solo necesitas nombrar bien el método y Spring se encarga del resto.

Qué sigue después de los query methods

Con estas herramientas tu pizzería ya puede buscar pizzas por nombre, validar si existen con Optional y mostrar las opciones más económicas según un precio máximo. La siguiente capa es el Paging and Sorting Repository, otro repositorio de Spring que permite paginar y ordenar consultas de forma nativa.

¿Has usado findTop o findFirst en tus proyectos? Cuéntame en los comentarios qué consultas estás resolviendo con query methods.