Native SQL queries in Spring Boot - Step-by-Step Execution

Concept Flow - Native SQL queries

Define Native SQL Query

↓

Annotate Repository Method

↓

Call Method in Service

↓

Spring Boot Executes SQL

↓

Return Results to Service

↓

Use Results in Application

This flow shows how a native SQL query is defined, linked to a repository method, executed by Spring Boot, and results returned for use.

Execution Sample

Spring Boot

public interface UserRepository extends JpaRepository<User, Long> {
  @Query(value = "SELECT * FROM users WHERE email = ?1", nativeQuery = true)
  User findByEmailNative(String email);
}

Defines a native SQL query in a Spring Data repository to find a user by email.

Execution Table

Step	Action	SQL Query	Parameter	Result
1	Call findByEmailNative("[e-mail]")	SELECT * FROM users WHERE email = ?1	[e-mail]	Query prepared
2	Spring Boot executes native SQL	SELECT * FROM users WHERE email = '[e-mail]'	[e-mail]	Database returns matching user row
3	Spring Boot maps result to User entity	N/A	N/A	User object created with data
4	Return User object to caller	N/A	N/A	User object with email [e-mail]
5	End	N/A	N/A	Method execution complete

💡 Method returns User object or null if no match found

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	Final
email	null	[e-mail]	[e-mail]	[e-mail]	[e-mail]
SQL Query	null	SELECT * FROM users WHERE email = ?1	SELECT * FROM users WHERE email = '[e-mail]'	N/A	N/A
User	null	null	null	User entity with data	User entity with data

Key Moments - 3 Insights

Why do we use nativeQuery = true in the @Query annotation?

Because it tells Spring Boot this is a raw SQL query, not JPQL. See execution_table step 1 where the query is prepared as native SQL.

How does Spring Boot map the SQL result to a User object?

Spring Boot uses the entity mapping defined for User to convert the database row into a User instance, as shown in execution_table step 3.

What happens if no user matches the email?

The query returns no rows, so Spring Boot returns null instead of a User object, ending the method as in execution_table step 5.

Visual Quiz - 3 Questions

Look at the execution_table, what SQL query is executed at step 2?

A SELECT email FROM users

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

C SELECT * FROM users WHERE email = ?1

D SELECT * FROM users

💡 Hint

Check the SQL Query column at step 2 in the execution_table.

At which step does Spring Boot create the User object from the database result?

A Step 3

B Step 2

C Step 1

D Step 4

💡 Hint

Look at the Result column describing object creation in the execution_table.

If the email parameter was null, how would the execution_table change?

A Step 1 would fail to prepare the query

B Step 3 would create a User with null email

C Step 2 would execute with email = null and return no user

D Step 4 would return a User object anyway

💡 Hint

Consider how SQL handles null parameters and the flow in execution_table steps 1 and 2.

Concept Snapshot

Native SQL queries in Spring Boot:
- Use @Query annotation with nativeQuery=true
- Write raw SQL inside value attribute
- Method parameters replace SQL placeholders
- Spring Boot executes SQL directly on DB
- Results map to entity objects automatically

Full Transcript

This visual execution shows how native SQL queries work in Spring Boot. First, you define a repository method with @Query and nativeQuery=true. The SQL query uses placeholders for parameters. When the method is called, Spring Boot prepares the SQL with the parameter values, executes it on the database, and gets the result. Then it maps the database row to a User entity object and returns it. If no row matches, it returns null. This process lets you run raw SQL while still using Spring Data repositories.

Practice

1. What annotation is used in Spring Boot to define a native SQL query inside a repository interface?

easy

A. @SqlQuery

B. @NativeQuery

C. @Query with nativeQuery = true

D. @SQLNative

Solution

1. Step 1: Recognize the annotation for queries in Spring Data JPA

   The @Query annotation is used to define custom queries in repository interfaces.

2. Step 2: Identify how to specify native SQL

   Setting nativeQuery = true inside @Query tells Spring Boot to treat the query as native SQL.

3. Final Answer:

   @Query with nativeQuery = true -> Option C

4. Quick Check:

   Native SQL queries use @Query(nativeQuery = true) [OK]

Hint: Look for @Query with nativeQuery true flag [OK]

Common Mistakes:

• Using a non-existent annotation like @NativeQuery
• Forgetting to set nativeQuery = true
• Confusing @Query with @SqlQuery
• Using @SQLNative which is invalid

2. Which of the following is the correct syntax to write a native SQL query in a Spring Boot repository method?

easy

A. @Query(value = "SELECT * FROM users", nativeQuery = true)

B. @Query(native = true, value = "SELECT * FROM users")

C. @NativeQuery("SELECT * FROM users")

D. @Query(sql = "SELECT * FROM users")

Solution

1. Step 1: Recall the correct attribute names in @Query

   The attribute for the query string is value, and to mark it native SQL, use nativeQuery = true.

2. Step 2: Check each option's syntax

   @Query(value = "SELECT * FROM users", nativeQuery = true) correctly uses @Query(value = "...", nativeQuery = true). Options B, C, and D use invalid attribute names or annotations.

3. Final Answer:

   @Query(value = "SELECT * FROM users", nativeQuery = true) -> Option A

4. Quick Check:

   @Query(value=..., nativeQuery=true) is correct syntax [OK]

Hint: Use value= for query and nativeQuery=true [OK]

Common Mistakes:

• Using native=true instead of nativeQuery=true
• Using @NativeQuery annotation which doesn't exist
• Using sql= instead of value= for query string
• Swapping attribute order incorrectly

3. Given this repository method:

@Query(value = "SELECT * FROM products WHERE price > ?1", nativeQuery = true)
List<Product> findExpensiveProducts(double minPrice);

What will be the result of calling findExpensiveProducts(100.0)?

medium

A. List of products with price less than 100.0

B. Empty list always

C. Syntax error due to ?1 placeholder

D. List of products with price greater than 100.0

Solution

1. Step 1: Understand the native SQL query with parameter

   The query selects all products where price is greater than the first parameter (?1), which is passed as 100.0.

2. Step 2: Predict the method output

   Calling findExpensiveProducts(100.0) returns products priced above 100.0, so the list contains those products.

3. Final Answer:

   List of products with price greater than 100.0 -> Option D

4. Quick Check:

   Native query with ?1 uses method parameter [OK]

Hint: ?1 matches first method parameter in native query [OK]

Common Mistakes:

• Thinking ?1 is invalid in native queries
• Confusing greater than with less than
• Assuming empty list without data
• Believing syntax error due to placeholder

4. Identify the error in this native query method:

@Query(value = "SELECT * FROM orders WHERE status = :status", nativeQuery = true)
List<Order> findByStatus(String status);

medium

A. Named parameter :status is not supported in native queries

B. Query string should use ?1 instead of :status

C. Missing nativeQuery = true flag

D. Method return type should be Optional<Order>

Solution

1. Step 1: Check parameter usage in native queries

   Native SQL queries in Spring Boot do not support named parameters like :status by default; they require positional parameters like ?1.

2. Step 2: Identify correct parameter syntax

   The query should use ?1 to refer to the first method parameter instead of :status.

3. Final Answer:

   Query string should use ?1 instead of :status -> Option B

4. Quick Check:

   Native queries use positional parameters like ?1 [OK]

Hint: Use ?1 for parameters in native queries, not :name [OK]

Common Mistakes:

• Using named parameters in native queries
• Forgetting nativeQuery = true
• Assuming return type must be Optional
• Confusing JPQL and native SQL syntax

5. You want to write a native SQL query in Spring Boot to update the price of all products in a category. Which method signature and annotation is correct?

hard

A. @Modifying
@Query(value = "UPDATE products SET price = price * 1.1 WHERE category = ?1", nativeQuery = true)
int increasePriceByCategory(String category);

B. @Query(value = "UPDATE products SET price = price * 1.1 WHERE category = ?1", nativeQuery = true)
void increasePriceByCategory(String category);

C. @Modifying
@Query(value = "UPDATE products SET price = price * 1.1 WHERE category = :category", nativeQuery = true)
int increasePriceByCategory(String category);

D. @Modifying
@Query(value = "UPDATE products SET price = price * 1.1 WHERE category = ?1")
int increasePriceByCategory(String category);

Solution

1. Step 1: Recognize update queries need @Modifying

   In Spring Boot, native update queries require the @Modifying annotation to indicate a modifying operation.

2. Step 2: Check parameter syntax and nativeQuery flag

   @Modifying @Query(value = "UPDATE products SET price = price * 1.1 WHERE category = ?1", nativeQuery = true) int increasePriceByCategory(String category); correctly uses positional parameter ?1 and sets nativeQuery = true. @Modifying @Query(value = "UPDATE products SET price = price * 1.1 WHERE category = :category", nativeQuery = true) int increasePriceByCategory(String category); uses named parameter which is invalid in native queries. @Modifying @Query(value = "UPDATE products SET price = price * 1.1 WHERE category = ?1") int increasePriceByCategory(String category); misses nativeQuery flag. @Query(value = "UPDATE products SET price = price * 1.1 WHERE category = ?1", nativeQuery = true) void increasePriceByCategory(String category); misses @Modifying.

3. Final Answer:

   @Modifying @Query(value = "UPDATE products SET price = price * 1.1 WHERE category = ?1", nativeQuery = true) int increasePriceByCategory(String category); -> Option A

4. Quick Check:

   Update native queries need @Modifying and nativeQuery=true [OK]

Hint: Use @Modifying and nativeQuery=true for update queries [OK]

Common Mistakes:

• Omitting @Modifying on update queries
• Using named parameters in native queries
• Forgetting nativeQuery=true flag
• Returning void instead of int for update count