Что такое нативный запрос в Hibernate?

# Нативный запрос в Hibernate

Нативный запрос (native query) — это прямой SQL-запрос, выполняемый в Hibernate без преобразования в HQL или использования критерий API. Это способ написать обычный SQL и получить результаты, обойдя ORM-слой.

Основные концепции

Нативные запросы используются, когда:

• Нужна высокая производительность и оптимизированный SQL
• Требуются специфичные для БД функции и синтаксис
• HQL недостаточно выразителен для сложного запроса
• Нужна сложная логика агрегации или аналитики

Синтаксис

Создание нативного запроса

Session session = sessionFactory.openSession();
NativeQuery<Product> query = session.createNativeQuery(
    "SELECT * FROM products WHERE price > ?1",
    Product.class
);
query.setParameter(1, 100.0);
List<Product> results = query.getResultList();

С использованием Parameter Objects (рекомендуется)

NativeQuery<Product> query = session.createNativeQuery(
    "SELECT * FROM products WHERE price > :minPrice AND category = :category",
    Product.class
);
query.setParameter("minPrice", 100.0);
query.setParameter("category", "Electronics");
List<Product> results = query.getResultList();

Маппирование результатов

Маппирование на сущность

NativeQuery<User> query = session.createNativeQuery(
    "SELECT id, name, email FROM users WHERE id = :id",
    User.class
);
query.setParameter("id", 1L);
User user = query.getSingleResult();

Маппирование на DTO

NativeQuery<UserDTO> query = session.createNativeQuery(
    "SELECT new map(id, name, email) FROM users WHERE active = true",
    UserDTO.class
);
List<UserDTO> results = query.getResultList();

Маппирование на Object[]

NativeQuery<Object[]> query = session.createNativeQuery(
    "SELECT id, name, email FROM users"
);
List<Object[]> results = query.getResultList();
for (Object[] row : results) {
    Long id = ((Number) row[0]).longValue();
    String name = (String) row[1];
    String email = (String) row[2];
}

Именованные нативные запросы

Для переиспользования можно определить запросы в аннотациях:

@Entity
@NamedNativeQuery(
    name = "User.findByEmail",
    query = "SELECT * FROM users WHERE email = :email",
    resultClass = User.class
)
public class User {
    // поля сущности
}

// Использование
Query query = session.createNamedQuery("User.findByEmail");
query.setParameter("email", "user@example.com");
User user = (User) query.getSingleResult();

Преимущества и недостатки

Преимущества

• Производительность: оптимизированный SQL, минимизирует overhead ORM
• Гибкость: доступ к специфичным возможностям БД (оконные функции, CTE, специальные синтаксисы)
• Контроль: полный контроль над выполняемым кодом
• Отладка: легче отладить проблемы производительности

Недостатки

• Зависимость от БД: SQL-запросы часто специфичны для конкретной СУБД
• Миграции: при изменении схемы нужно обновлять запросы вручную
• Безопасность: требует аккуратности с SQL-инъекциями (всегда использовать параметры!)
• Тестируемость: сложнее тестировать в изоляции от БД

Best Practices

// ✅ ВСЕГДА использовать параметризованные запросы
NativeQuery<Product> query = session.createNativeQuery(
    "SELECT * FROM products WHERE price > :price",
    Product.class
);
query.setParameter("price", 100.0);

// ❌ НИКОГДА не конкатенировать строки!
// String sql = "SELECT * FROM products WHERE price > " + price; // SQL-инъекция!

// ✅ Использовать лимиты для больших результатов
query.setMaxResults(1000);

// ✅ Кэшировать результаты, если нужно
query.setCacheable(true);

Когда использовать нативные запросы

Нативные запросы — это инструмент для специальных случаев:

• Сложные отчёты с аналитикой (window functions)
• Bulk операции (UPDATE/DELETE на миллионах записей)
• Интеграция с legacy системами
• Запросы, где производительность критична

В большинстве случаев HQL или Criteria API достаточно и предпочтительнее, так как выше переносимость и простота поддержки.