Native SQL Queries in Hibernate

Introduction

HQL covers the vast majority of queries you will write against your entities, but it is not the only option. Sometimes you need a database-specific function, a complex analytical query, or a hand-tuned statement that HQL simply cannot express cleanly. For those cases, Hibernate lets you drop down to native SQL while still getting entity mapping and Session management.

Why Native SQL?

HQL is deliberately database-agnostic and object-oriented, which means it does not expose every feature a specific database offers. Common reasons to reach for native SQL include vendor-specific functions (like MySQL's GROUP_CONCAT), complex window functions, stored procedure calls, or a query that is already tuned and tested as raw SQL that you do not want to rewrite.

createNativeQuery Basics

Session.createNativeQuery() accepts a plain SQL string, written exactly as your database expects it — real table and column names, not entity and field names.

import org.hibernate.query.NativeQuery;
import java.util.List;

Session session = factory.openSession();

NativeQuery<Object[]> query = session.createNativeQuery(
    "SELECT id, name, salary FROM employees WHERE salary > :minSalary"
);
query.setParameter("minSalary", 50000);

List<Object[]> rows = query.getResultList();

for (Object[] row : rows) {
    System.out.println("ID: " + row[0] + ", Name: " + row[1] + ", Salary: " + row[2]);
}

session.close();

Mapping to Entities

If you select every column of a mapped entity, Hibernate can return fully-managed entity instances instead of raw Object[] rows, by telling createNativeQuery which entity class to map onto.

NativeQuery<Employee> query = session.createNativeQuery(
    "SELECT * FROM employees WHERE department = :dept",
    Employee.class
);
query.setParameter("dept", "Engineering");

List<Employee> employees = query.getResultList();

for (Employee e : employees) {
    System.out.println(e.getName() + " - " + e.getSalary());
}

Scalar and DTO Results

For queries that do not map cleanly onto one entity — like aggregations across a join — you can select individual columns and map them into a plain constructor, similar to HQL's constructor expressions.

NativeQuery<Object[]> query = session.createNativeQuery(
    "SELECT department, COUNT(*), AVG(salary) FROM employees GROUP BY department"
);

List<Object[]> results = query.getResultList();

for (Object[] row : results) {
    String department = (String) row[0];
    Number count = (Number) row[1];
    Number avgSalary = (Number) row[2];
    System.out.println(department + ": " + count + " employees, avg salary " + avgSalary);
}

Named Native Queries

Just like named HQL queries, a native query can be declared once on an entity with @NamedNativeQuery and reused by name, keeping the raw SQL out of your business logic.

import javax.persistence.*;

@Entity
@Table(name = "employees")
@NamedNativeQuery(
    name = "Employee.findHighEarners",
    query = "SELECT * FROM employees WHERE salary > :minSalary",
    resultClass = Employee.class
)
public class Employee {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private Double salary;

    // Getters and setters
}

List<Employee> highEarners = session
    .createNamedQuery("Employee.findHighEarners", Employee.class)
    .setParameter("minSalary", 60000)
    .getResultList();

HQL vs Native SQL

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

Native SQL is Hibernate's escape hatch for the queries HQL was never meant to express — vendor-specific functions, tuned reports, and complex aggregations — while still benefiting from parameter binding and, where possible, entity mapping. Use it deliberately, and keep HQL as your default.