Ответ
Параметр nativeQuery = true в аннотации @Query указывает, что запрос написан на нативном SQL диалекте конкретной СУБД, а не на JPQL (Java Persistence Query Language) или HQL (Hibernate Query Language).
Когда использовать?
- Для сложных запросов, которые сложно или невозможно выразить в JPQL (например, рекурсивные запросы, оконные функции, специфичные операторы).
- Когда требуется максимальная производительность и вы хотите использовать оптимизированный, специфичный для БД SQL.
- Для вызова хранимых процедур или использования нестандартных функций СУБД.
Пример:
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
public interface UserRepository extends JpaRepository<User, Long> {
// Нативный запрос с использованием специфичного для PostgreSQL синтаксиса
@Query(value = """
SELECT u.*,
AVG(o.total) OVER (PARTITION BY u.region) as avg_region_total
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.active = true AND u.registration_date > :sinceDate
""",
nativeQuery = true) // <-- Ключевой параметр
List<Object[]> findActiveUsersWithRegionalAvg(@Param("sinceDate") LocalDate sinceDate);
}
Важные ограничения и особенности:
| Аспект | Нативный запрос (nativeQuery = true) |
JPQL-запрос (по умолчанию) |
|---|---|---|
| Переносимость | ❌ Нет. Запрос привязан к диалекту конкретной СУБД. | ✅ Да. Hibernate транслирует JPQL в SQL нужной БД. |
| Проверка | ❌ Проверяется только при выполнении. Ошибки в именах полей/таблиц приведут к исключению времени выполнения. | ✅ Проверяется на этапе компиляции или запуска приложения. |
| Синтаксис | Синтаксис SQL вашей БД (например, SELECT * FROM table). |
Синтаксис JPQL (работает с сущностями и их полями, например, SELECT u FROM User u). |
| Пагинация | Требует аккуратной настройки. Для Pageable может потребоваться отдельный запрос для count(*). |
Поддерживается автоматически. |
| Возвращаемый тип | Часто List<Object[]> или List<Tuple>, если результат не соответствует сущности. Может быть сущностью, если структура результата совпадает с ее маппингом. |
Может возвращать сущности, проекции (DTO), скалярные значения. |
Рекомендация: Используйте нативные запросы только тогда, когда возможностей JPQL/HQL недостаточно, и осознавайте потерю переносимости.