@Query for custom JPQL in Spring Boot - Step-by-Step Execution

Concept Flow - @Query for custom JPQL

Define Repository Interface

↓

Add @Query Annotation with JPQL

↓

Spring Data Parses JPQL Query

↓

Method Called in Service

↓

JPQL Query Executed on Database

↓

Results Returned to Caller

Shows how a custom JPQL query is defined in a repository, parsed by Spring Data, executed, and results returned.

Execution Sample

Spring Boot

public interface UserRepository extends JpaRepository<User, Long> {
  @Query("SELECT u FROM User u WHERE u.email = :email")
  User findByEmail(@Param("email") String email);
}

Defines a repository method with a custom JPQL query to find a User by email.

Execution Table

Step	Action	JPQL Query	Parameter	Result
1	Call findByEmail("[e-mail]")	SELECT u FROM User u WHERE u.email = :email	email = "[e-mail]"	Query prepared with parameter
2	Spring Data executes JPQL	SELECT u FROM User u WHERE u.email = '[e-mail]'	email = "[e-mail]"	Database runs query
3	Database returns matching User entity	N/A	N/A	User object with email [e-mail]
4	Method returns User to caller	N/A	N/A	User object returned

💡 Query completes after returning matching User or null if none found

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
email	N/A	"[e-mail]"	"[e-mail]"	"[e-mail]"	"[e-mail]"
JPQL Query	N/A	"SELECT u FROM User u WHERE u.email = :email"	"SELECT u FROM User u WHERE u.email = '[e-mail]'"	N/A	N/A
Result	N/A	Query prepared	Query executed	User entity fetched	User returned

Key Moments - 3 Insights

Why do we use :email in the JPQL query instead of directly putting the email string?

Using :email is a parameter placeholder. It helps prevent errors and SQL injection. The actual value is set later, as shown in execution_table step 1.

What happens if no User matches the email?

The query returns null or empty result. The method then returns null, as the database found no matching entity (see execution_table step 3).

Can we use native SQL instead of JPQL in @Query?

Yes, by adding nativeQuery = true in @Query. But here we use JPQL which works with entity objects, not tables directly.

Visual Quiz - 3 Questions

Look at the execution_table, what is the JPQL query after Step 2?

A "SELECT u FROM User u WHERE u.email = '[e-mail]'"

B "SELECT * FROM users WHERE email = '[e-mail]'"

C "SELECT u FROM User u WHERE u.email = :email"

D "SELECT u FROM User u"

💡 Hint

Check the JPQL Query column in execution_table row for Step 2

At which step does the database actually run the query?

A Step 1

B Step 2

C Step 3

D Step 4

💡 Hint

Look at the Action column describing when Spring Data executes JPQL

If the parameter email was changed to "[e-mail]", what changes in the execution_table?

A Only the Parameter column changes to email = "[e-mail]"

B The JPQL Query column changes to use '[e-mail]' instead of '[e-mail]'

C Both Parameter and JPQL Query columns change accordingly

D No changes in the table

💡 Hint

Check how parameter substitution affects JPQL Query and Parameter columns in steps 1 and 2

Concept Snapshot

@Query lets you write custom JPQL in Spring Data repositories.
Use :paramName as placeholders for parameters.
Spring Data parses and runs the JPQL when method is called.
Results map to entity objects returned by the method.
Use @Param to bind method parameters to JPQL placeholders.

Full Transcript

This visual shows how @Query with custom JPQL works in Spring Boot. First, you define a repository interface method and annotate it with @Query containing JPQL. The JPQL uses placeholders like :email. When the method is called with an argument, Spring Data prepares the query by replacing placeholders with actual values. Then it executes the JPQL on the database. The database returns matching entity objects. Finally, the method returns these objects to the caller. Variables like the email parameter and JPQL query string change step-by-step as the query is prepared and run. Key points include why placeholders are used for safety and flexibility, what happens if no results are found, and that JPQL works with entities, not raw tables. The quiz checks understanding of query substitution, execution timing, and parameter effects.