คำค้นหา JPQL และเนทีฟด้วย @Query

Spring Data JPA can derive queries from method names like findByLastName, but derived queries break down for anything non-trivial: joins across entities, aggregations, custom projections, or fine-tuned SQL.

The @Query annotation lets you attach an explicit query to a repository method. You write the query once, declaratively, and Spring binds the method's parameters and maps the result.

• JPQL — object-oriented query language that works against entities and fields.
• Native SQL — raw database SQL when you need vendor features or hand-tuned queries.

JPQL looks like SQL but operates on entity names and Java field names, not table and column names. Here User is the entity class and email is a Java field.

Notice the placeholder ?1 — this is a positional parameter bound to the first method argument.

Positional parameters (?1, ?2) work, but they break when you reorder arguments. Named parameters are clearer and safer: write :name in the query and bind it with @Param("name").

• The string in @Param must match the :placeholder exactly.
• Order of method arguments no longer matters.

Both styles bind method arguments into the query, but they differ in maintainability.

• Positional (?1) — concise for one or two params; fragile when you add or reorder arguments.
• Named (:status) — self-documenting and resilient to refactoring; preferred for queries with multiple parameters.

The team standard in Spring Boot 4 projects is to favor named parameters for readability. Reserve positional parameters for very short queries.

When you need database-specific SQL — window functions, vendor extensions, or a hand-optimized statement — set nativeQuery = true. Now the query runs as raw SQL against table and column names, not entity fields.

The result is still mapped back to the User entity because the selected columns match the entity's table.

Default to JPQL; reach for native SQL only when JPQL can't express what you need.

• JPQL — portable across databases, refactor-safe (uses Java field names), integrates with the persistence context.
• Native — full SQL power and vendor features, but ties you to one database dialect and bypasses some JPA conveniences.

A common pitfall: in native queries LIKE wildcards and pagination must follow your database's SQL, not JPQL rules.

Often you don't need the whole entity — just a few columns. A projection returns a lightweight view instead of a full User.

Define an interface with getters; Spring matches each getter to a selected alias. This loads only the columns you ask for.

For an interface projection to bind, each selected expression must be aliased to match the getter name. The getter getEmail() maps to alias email.

• SELECT u.email AS email binds to getEmail().
• Omitting the alias on a computed column leaves the getter unmapped and returns null.

This holds for both JPQL and native projection queries.

JPQL also supports constructor expressions: build a DTO directly in the query with the NEW keyword. You must use the fully-qualified class name and match a constructor's parameter order.

This gives you an immutable, typed result object instead of an interface proxy.

@Query can also run UPDATE and DELETE statements. These require @Modifying so Spring executes them as updates rather than selects, and they typically run inside a @Transactional method.

The return value is the count of affected rows.

JPQL parameter binding mirrors how you'd substitute values yourself. The snippet below is plain Java that demonstrates the named-parameter substitution idea behind :status and :minAge — no database required.

In real code Spring does this binding safely via prepared statements; this just illustrates the concept.

Test your understanding of @Query parameter binding and projections.

You now know how to write explicit queries with @Query:

• JPQL works on entity and field names; native SQL (nativeQuery = true) works on tables and columns.
• Bind values with positional (?1) or, preferably, named (:name + @Param) parameters.
• Interface projections need aliases matching getter names; constructor expressions (SELECT new ...) build typed DTOs.
• Use @Modifying (with @Transactional) for UPDATE/DELETE queries.

Default to JPQL for portability; drop to native SQL only when you truly need database-specific power.