新人と先輩の会話形式で理解しよう

新人

「SQLは少しだけ知ってるんですが、JPQLって何ですか？違いがよくわからなくて……」

先輩

「JPQLは、Javaのエンティティに対してSQLのような形でデータ操作をするためのクエリ言語だよ。Spring Data JPAでよく使われるんだ。」

新人

「SQLと何が違うんでしょうか？」

先輩

「じゃあ今日は、JPQLの基本構文と、SELECT・WHEREの使い方を見ていこうか。」

1. JPQLとは何か？（SQLとの違い）

JPQL（Java Persistence Query Language）は、Javaのエンティティクラスを対象にしたクエリ言語です。見た目はSQLとよく似ていますが、大きな違いは「テーブル名ではなくエンティティ名」を使うという点です。

例えば、Userというエンティティがある場合、SQLでは次のように書きます：


SELECT * FROM users;

これがJPQLでは、以下のようになります：


SELECT u FROM User u

ここではusersというテーブル名ではなく、JavaのUserというクラスを使っているのが特徴です。オブジェクト指向に基づいたデータアクセスを行うための仕組みで、SQLと違いJPAのエンティティに対して実行されます。

2. SELECT文の基本構文と意味

JPQLのSELECT文は、特定のエンティティのデータを取得する際に使います。基本的な構文は以下のとおりです：


SELECT エンティティのエイリアス FROM エンティティ名 エイリアス

具体例として、全てのユーザーを取得するクエリは次のようになります：


SELECT u FROM User u

このクエリでは、Userというエンティティのデータをuという別名で取得しています。JPAでは、このようにエンティティ名を直接指定することで、JPAの仕組みが適切にSQLに変換してデータベースへアクセスしてくれます。

3. WHERE句で条件を指定する方法

JPQLで特定の条件に一致するデータだけを取得したい場合には、WHERE句を使います。基本的な構文は以下のようになります：


SELECT u FROM User u WHERE u.name = '佐藤'

このように書くことで、「名前が『佐藤』であるユーザーのみ」を取得することができます。SQLのWHERE句とほとんど同じように使えるため、SQLに慣れている人には親しみやすいです。

条件は複数指定することも可能で、例えば「名前が佐藤で、年齢が30歳」の場合は次のようになります：


SELECT u FROM User u WHERE u.name = '佐藤' AND u.age = 30

このように、JPQLのWHERE句は、Javaのエンティティのフィールドをそのまま条件に使える点が大きな利点です。特にSpring Data JPAと組み合わせると、@Queryアノテーションと一緒に使えて便利です。

4. @Queryアノテーションを使ったJPQLの定義方法

@Queryアノテーションは、Spring Data JPAでJPQLを明示的に記述したい場合に使用するものです。リポジトリインターフェースにJPQLを直接書くことで、複雑な検索条件や複数条件のクエリも定義できます。

まず、UserRepositoryインターフェースにJPQLを使ったメソッドを定義してみましょう。


import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

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

この例では、名前が一致するユーザーを取得するJPQLを@Queryで記述しています。:nameのようにパラメータをプレースホルダーとして使うことで、外部から値を渡すことが可能になります。

5. 実際のJPQL使用例（名前や年齢での絞り込み）

JPQLを使えば、複数の条件を組み合わせたデータの取得も簡単にできます。例えば「名前が佐藤」で「年齢が30歳以上」のユーザーを取得するには、以下のようなコードを書きます。


@Query("SELECT u FROM User u WHERE u.name = :name AND u.age >= :age")
List<User> findByNameAndMinAge(@Param("name") String name, @Param("age") int age);

このように@Queryの中でAND演算子や比較演算子（>=）を使うことで、複雑な検索条件も柔軟に記述できます。

次に、姓が「田中」または「佐藤」のユーザーを取得するJPQLも紹介します。


@Query("SELECT u FROM User u WHERE u.name = '田中' OR u.name = '佐藤'")
List<User> findTanakaOrSato();

OR演算子を使うことで、複数条件のいずれかに一致するデータを取得可能です。こうした記述は、検索機能や管理画面でのフィルター処理などに役立ちます。

6. コントローラでの使い方（@Controllerを使ったデータ取得表示）

JPQLを@Queryで定義したら、@Controllerを使ってデータをHTMLテンプレートに表示することができます。以下は名前検索の結果を表示する例です。


import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;

@Controller
public class UserController {

    @Autowired
    private UserRepository userRepository;

    @GetMapping("/search")
    public String searchUsers(@RequestParam("name") String name, Model model) {
        List<User> users = userRepository.findUsersByName(name);
        model.addAttribute("users", users);
        return "user-list";
    }
}

このコードでは、クエリパラメータとして渡されたnameを使って、UserRepositoryからユーザー一覧を取得し、それをビューに渡しています。テンプレート側では${users}でループ表示できます。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>検索結果</title>
</head>
<body>
    <h2>検索結果一覧</h2>
    <ul>
        <li th:each="user : ${users}">
            名前：<span th:text="${user.name}"></span>
        </li>
    </ul>
</body>
</html>

このように@QueryとJPQLを使えば、自由度の高いデータ取得が可能になり、Spring MVCのコントローラと組み合わせて実用的なWebアプリケーションを構築できます。

7. JPQLでのパラメータ指定方法（?1, :nameなど）

JPQLでデータを絞り込む際には、パラメータを使って動的に値を渡すのが一般的です。パラメータの指定方法には「位置指定パラメータ（?1など）」と「名前付きパラメータ（:nameなど）」の2種類があります。

位置指定パラメータの例は以下のようになります：


@Query("SELECT u FROM User u WHERE u.name = ?1")
List<User> findByName(String name);

この場合、?1はメソッドの第1引数であるnameに対応しています。番号は1から始まり、順番に割り当てられます。

一方、名前付きパラメータを使うと、より読みやすく柔軟に書けます：


@Query("SELECT u FROM User u WHERE u.name = :name")
List<User> findByName(@Param("name") String name);

こちらは引数に@Paramを使って名前を明示的に指定します。可読性が高く、複数のパラメータがある場合に特に便利です。

8. JPQL使用時の注意点（構文ミス、エンティティ名の使用、型の一致）

JPQLはSQLに似ていますが、エラーが起きやすいポイントもあります。以下に代表的な注意点を紹介します。

エンティティ名とフィールド名を使う

JPQLではテーブル名やカラム名ではなく、Javaのエンティティ名やフィールド名を使います。SQLのつもりでFROM usersやWHERE user_nameのように書くとエラーになります。

型の一致に注意

パラメータに渡す型は、エンティティのフィールドと一致させる必要があります。ageがintで定義されている場合、文字列を渡すとエラーになります。

構文エラーの例

次のような構文ミスもよくあります：


// 誤った記述（エンティティ名の代わりにテーブル名を使用している）
@Query("SELECT u FROM users u WHERE u.name = :name")

正しくは次のようにエンティティ名Userを使います：


@Query("SELECT u FROM User u WHERE u.name = :name")

このような構文ミスは、起動時や実行時に例外として表示されます。初心者のうちは、1つずつ確実に文法をチェックしていくことが大切です。

9. JPQLの次に学ぶべき内容（UPDATE, DELETE, ネイティブSQL）

JPQLのSELECTとWHERE句の基本を学んだら、次のステップとしてUPDATE文やDELETE文も学びましょう。JPQLではデータの取得だけでなく、データの更新や削除も可能です。

UPDATE文の基本

次のように書くことで、名前を更新する処理を実装できます。


@Modifying
@Query("UPDATE User u SET u.name = :newName WHERE u.id = :id")
void updateUserName(@Param("id") Long id, @Param("newName") String newName);

このようなUPDATEクエリは、データベースの変更を伴うため@Modifyingアノテーションを付ける必要があります。

DELETE文の基本

データ削除も同様に可能です：


@Modifying
@Query("DELETE FROM User u WHERE u.id = :id")
void deleteUserById(@Param("id") Long id);

DELETEも更新と同様に@Modifyingが必須です。

ネイティブSQLの活用

どうしてもSQLでしか実現できない操作がある場合は、ネイティブSQLを使う方法もあります。JPQLとは異なり、データベース固有の構文が使えます。


@Query(value = "SELECT * FROM users WHERE age >= ?1", nativeQuery = true)
List<User> findUsersByAge(int age);

nativeQuery = trueを指定することで、SQLとして直接実行できます。ただし、テーブル名やカラム名を使うため、データベースのスキーマ設計に依存します。基本的にはJPQLでの実装を優先しましょう。

ここまで学んだ内容を活かして、今後はJPQLによる更新・削除やネイティブSQLの使い方も習得していくと、Springアプリケーションの開発力が一段と高まります。

まとめ

JPQLによるデータ取得の全体像を振り返る

この記事では、JPQLを使ったデータ取得について、SELECT文とWHERE句を中心に、基本構文から実践的な使い方まで段階的に解説してきました。 JPQLはSQLと見た目が似ているため、最初は「SQLと同じもの」と誤解されがちですが、実際にはエンティティを対象としたオブジェクト指向のクエリ言語である点が大きな特徴です。テーブル名やカラム名ではなく、エンティティ名とフィールド名を使うという考え方を理解することで、 JPQLの仕組みが自然と腑に落ちてきます。

特に初心者の方にとって重要なのは、「JPQLはエンティティを取得するための言語である」という意識を持つことです。 SELECT文ではエンティティ全体を取得し、 WHERE句ではエンティティのフィールドに対して条件を指定します。この基本ルールを押さえるだけで、JPQLの多くのクエリは読み解けるようになります。

SELECT文とWHERE句の役割を整理する

JPQLのSELECT文は、「どのエンティティを取得するか」を指定するためのものです。 SQLのようにカラムを一つずつ指定するのではなく、エンティティ単位で取得する点がJPQLらしいポイントです。そのため、SELECT句で指定したエンティティは、そのままJavaのオブジェクトとして扱うことができます。

WHERE句は、取得対象を絞り込むための条件指定に使われます。名前や年齢などのフィールドを使って条件を設定できるため、ビジネスロジックに近い形でクエリを記述できます。 ANDやORを使った複数条件の指定や、比較演算子による条件付けは、実際の検索画面や管理機能で頻繁に登場します。

@Queryとパラメータ指定の重要性

Spring Data JPAでは、@Queryアノテーションを使うことで、 JPQLをリポジトリインターフェースに直接記述できます。これにより、メソッド名だけでは表現しにくい検索条件や、複数条件を組み合わせた柔軟なクエリを定義できます。特に、名前付きパラメータを使ったJPQLは可読性が高く、後からコードを見返したときにも理解しやすい書き方です。

パラメータ指定を正しく使うことで、ユーザー入力に応じた動的な検索処理が実現できます。コントローラから受け取った値をそのままJPQLに渡し、検索結果を画面に表示する流れは、 Spring MVCとJPAを組み合わせた開発の基本形と言えるでしょう。

JPQL理解を深めるためのサンプル整理

ここで、この記事で学んだ内容を踏まえた、シンプルなJPQLのサンプルを改めて確認しておきましょう。実務でもよく使われる基本形です。


@Query("SELECT u FROM User u WHERE u.name = :name AND u.age >= :age")
List<User> findByNameAndAge(
    @Param("name") String name,
    @Param("age") int age
);

このように、エンティティ名とフィールド名を使って条件を指定することで、 SQLに近い感覚でありながら、JPAらしいデータ取得が可能になります。最初は短いクエリから書き始め、少しずつ条件を増やしていくことで、 JPQLへの理解は確実に深まっていきます。

次の学習につなげるために

SELECTとWHERE句の基本を理解できたら、 UPDATE文やDELETE文といったデータ更新系のJPQLにも挑戦してみましょう。また、どうしてもJPQLでは表現しづらい処理が必要になった場合には、ネイティブSQLを使う選択肢があることも覚えておくと安心です。ただし、基本はJPQLを優先し、エンティティ中心の設計を意識することが重要です。

JPQLを正しく使いこなせるようになると、 Springアプリケーションにおけるデータ取得処理が一気に読みやすくなり、保守性も向上します。焦らず、一つひとつのクエリの意味を理解しながら、着実にスキルを積み重ねていきましょう。

先生と生徒の振り返り会話

生徒

「JPQLって最初は難しそうだと思っていましたが、エンティティを対象にしていると分かると、 SQLよりも読みやすく感じてきました」

先生

「その感覚はとても大切ですね。 JPQLはデータベースよりも、 Javaのオブジェクトを意識して書くと理解しやすくなります」

生徒

「WHERE句で条件を組み合わせると、検索機能が一気に実用的になるのが分かりました」

先生

「そうですね。検索条件をどう設計するかは、実務でもとても重要なポイントになります」

生徒

「次はUPDATEやDELETEも勉強して、 JPQLをもっと使いこなせるようになりたいです」