@Query Annotation in Spring Data JPA

Direct Answer

@Query defines JPQL by default and native SQL when nativeQuery=true. Use it when an explicit query communicates the required projection, join, aggregation, fetch plan, or predicate more clearly than method-name derivation. Bind values as parameters. There is no meaningful universal method-name length threshold at which @Query becomes required.

Code Example

public interface OrderRepository extends JpaRepository<Order, Long> {

    @Query("SELECT o FROM Order o WHERE o.status = :status") // JPQL (portable)
    List<Order> byStatus(@Param("status") String status);

    @Query(value = "SELECT * FROM orders WHERE notes ILIKE %:term%",
           nativeQuery = true) // native: PostgreSQL ILIKE
    List<Order> searchNotes(@Param("term") String term);

    @Query("SELECT new com.example.dto.OrderSummary(o.id, o.total) FROM Order o")
    List<OrderSummary> summaries(); // DTO projection via constructor expression
}

Common Mistakes & Pitfalls

• Native SQL by default — loses portability and field validation; use JPQL first.
• Missing @Modifying on UPDATE/DELETE — runtime exception; @Query expects SELECT otherwise.
• No transaction — even with @Modifying, the write needs a @Transactional boundary.
• Stale cache after bulk update — without clearAutomatically = true, the next read may return old cached entities.