Что означает параметр `nativeQuery = true` в аннотации `@Query` в Spring Data JPA / Hibernate?

«Что означает параметр `nativeQuery = true` в аннотации `@Query` в Spring Data JPA / Hibernate?» — вопрос из категории Hibernate, который задают на 10% собеседований Java Разработчик. Ниже — развёрнутый ответ с разбором ключевых моментов.

Ответ

Параметр 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 недостаточно, и осознавайте потерю переносимости.