> For the complete documentation index, see [llms.txt](https://www.pranaypourkar.co.in/the-programmers-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pranaypourkar.co.in/the-programmers-guide/spring/spring-features/spring-persistence/jpa-java-persistence-api/querying-data/named-queries.md).

# Named Queries

## About

**Named Queries** in JPA are pre-defined static queries that are given a name and defined either via annotations or XML. These queries are typically written in JPQL and are associated with entity classes. Once defined, they can be invoked by name through the `EntityManager` or Spring Data JPA repository.

## Why use Named Queries?

* Centralized query management
* Reuse across multiple classes/methods
* Better for static, frequently-used queries
* Pre-compilation in some JPA implementations for performance boost

## Characteristics

<table data-full-width="true"><thead><tr><th width="253.390625">Feature</th><th>Description</th></tr></thead><tbody><tr><td><strong>Static</strong></td><td>Defined once and reused; cannot be dynamically changed.</td></tr><tr><td><strong>Precompiled</strong></td><td>May be compiled during startup (depends on JPA provider like Hibernate).</td></tr><tr><td><strong>Scoped to Entity</strong></td><td>Defined on an entity class.</td></tr><tr><td><strong>Readable and Reusable</strong></td><td>Named queries can be referenced easily throughout the application.</td></tr><tr><td><strong>Better for Shared Queries</strong></td><td>Useful when multiple services/repositories use the same query.</td></tr></tbody></table>

## Syntax Structure

### Annotation-based Named Query

Use `@NamedQuery` or `@NamedQueries` on the entity class.

```java
@Entity
@NamedQuery(
    name = "Employee.findByDepartment",
    query = "SELECT e FROM Employee e WHERE e.department = :dept"
)
public class Employee {
    @Id
    private Long id;
    private String name;
    private String department;
}
```

### XML-based Named Query (persistence.xml)

```xml
<named-query name="Employee.findByDepartment">
    <query>SELECT e FROM Employee e WHERE e.department = :dept</query>
</named-query>
```

### Accessing Named Query

**Using `EntityManager`:**

```java
List<Employee> employees = entityManager
    .createNamedQuery("Employee.findByDepartment", Employee.class)
    .setParameter("dept", "IT")
    .getResultList();
```

**Using Spring Data JPA:**

```java
@Query(name = "Employee.findByDepartment")
List<Employee> findByDepartment(@Param("dept") String department);
```

{% hint style="info" %}
**Note:** If the named query is not found, we’ll get a runtime error.
{% endhint %}

{% hint style="info" %}
`@Query("SELECT e FROM Employee e WHERE e.department = :dept")`\
`List findByDepartment(@Param("dept") String department);`<br>

This is not a named query — it’s an inline JPQL query, and it's often preferred for simplicity when the query is short or used in only one place.
{% endhint %}

## Where Can You Declare Named Queries?

### 1. **On the Entity Class (Most Common & Recommended)**

This is the standard and preferred way.

```java
@Entity
@NamedQuery(
    name = "Employee.findByDepartment",
    query = "SELECT e FROM Employee e WHERE e.department = :dept"
)
public class Employee {
    // fields...
}
```

The JPA provider scans the entity class and registers the query automatically at startup.

### 2. **In `persistence.xml` (Less Common)**

We can define named queries in XML instead of annotations.

```xml
<named-query name="Employee.findByDepartment">
    <query>SELECT e FROM Employee e WHERE e.department = :dept</query>
</named-query>
```

Useful when:

* We don’t want query logic in code.
* We are externalizing queries for maintainability or tools.

### 3. **In Mapped Superclass or Embeddable?**

**Not supported.** We cannot define `@NamedQuery` inside a `@MappedSuperclass` or `@Embeddable`.

### 4. **Outside Entity Class?**

There’s no support for declaring named queries in arbitrary classes or repositories.

However, if we're using **Spring Data JPA**, we can define static queries using `@Query` in repository interfaces **instead of NamedQuery**.

```java
@Query("SELECT e FROM Employee e WHERE e.department = :dept")
List<Employee> findByDepartment(@Param("dept") String dept);
```

Equivalent in functionality, but avoids the need for `@NamedQuery`.

## Examples

### 1. Find Employees by Department

```java
@NamedQuery(
    name = "Employee.findByDepartment",
    query = "SELECT e FROM Employee e WHERE e.department = :dept"
)
```

```java
List<Employee> result = em.createNamedQuery("Employee.findByDepartment", Employee.class)
                          .setParameter("dept", "Sales")
                          .getResultList();
```

### 2. Find Employees with Salary Above Threshold

```java
@NamedQuery(
    name = "Employee.findHighEarners",
    query = "SELECT e FROM Employee e WHERE e.salary > :minSalary"
)
```

### 3. Count Employees in Department

```java
@NamedQuery(
    name = "Employee.countByDepartment",
    query = "SELECT COUNT(e) FROM Employee e WHERE e.department = :dept"
)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.pranaypourkar.co.in/the-programmers-guide/spring/spring-features/spring-persistence/jpa-java-persistence-api/querying-data/named-queries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.