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

新人

「Spring Bootでデータベースからデータを取り出すとき、JPQLっていうのを使うって聞いたんですけど、SQLとは違うんですか？」

先輩

「そうだね。JPQLはSQLに似てるけど、使い方や対象がちょっと違うんだ。Javaのエンティティを操作するためのクエリ言語なんだよ。」

新人

「なるほど。エンティティって何でしたっけ？」

先輩

「いい質問だね。まずはJPQLの概要とSQLとの違い、それからエンティティの準備について順番に解説していこうか。」

1. JPQLとは何か

JPQLとは「Java Persistence Query Language（ジャバ・パーシステンス・クエリ・ランゲージ）」の略で、Spring BootなどのJavaアプリケーションでエンティティを対象にデータベース操作を行うための言語です。初心者にとっては、SQLと何が違うのかが最初の疑問だと思います。

SQLはテーブルやカラムを直接指定して操作しますが、JPQLはJavaのクラス（Entity）とそのプロパティを指定します。つまり、データベースの構造そのものではなく、Javaで定義された構造を使ってクエリを書くのです。

たとえば、SQLでは次のように書きます。


SELECT * FROM users WHERE name = 'Taro';

しかし、JPQLでは以下のように書きます。


SELECT u FROM User u WHERE u.name = 'Taro'

ここでのUserはエンティティクラスで、uはエイリアスです。u.nameという形で、Javaクラスのフィールドを条件に使っています。

このように、JPQLはオブジェクト指向に沿ったクエリを記述できるので、Spring Bootとの親和性が高く、初心者でも慣れるととても扱いやすいです。

2. JPQLを使うための準備

JPQLを使うには、まずエンティティクラスを定義しておく必要があります。エンティティとは、データベースのテーブルと対応するJavaのクラスです。Spring Bootでは、@Entityアノテーションを使って定義します。

以下は、Userという名前のエンティティクラスの例です。


package com.example.demo.entity;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;

@Entity
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String name;
    private int age;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }
}

このクラスを定義しておくことで、JPQLでUserクラスを対象にしたクエリを発行できるようになります。

次に、JPQLを実行するためには、JpaRepositoryを継承したリポジトリインターフェースを作成します。


package com.example.demo.repository;

import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
}

このUserRepositoryを通じて、JPQLを使ったデータの取得や保存、削除などが可能になります。

リポジトリは、Spring Bootが自動的にインスタンス化してくれるので、@Controllerの中で注入して使うことができます。

以上が、JPQLを使うための基本的な準備となります。次回は、JPQLで実際にどのようにデータを取得するのか、クエリの書き方について詳しく見ていきましょう。

3. JPQLの基本文法

JPQL（Java Persistence Query Language）の基本的な構文は、SQLに似ていますが、テーブルやカラム名の代わりにJavaのエンティティクラス名とそのフィールド名を使用する点が大きく異なります。JPQLは、SELECT、FROM、WHEREなど、SQLと同じ構文を使いますが、対象はオブジェクトになります。

例えば、以下のような書き方が基本です。


SELECT u FROM User u WHERE u.age > 20

このクエリは、「Userというエンティティのうち、年齢が20歳より大きいユーザーを取得する」という意味です。uはエンティティのエイリアス（別名）として使います。

他にも以下のような構文があります。


SELECT u.name FROM User u
SELECT u FROM User u ORDER BY u.name ASC
SELECT u FROM User u WHERE u.name LIKE '%Taro%'

このように、JPQLではEntityのプロパティを直接参照することで、柔軟な検索や並び替えを実現できます。

4. 実際のクエリ記述例

それでは、実際にJPQLを使った検索クエリを記述してみましょう。まず、名前でユーザーを検索するような処理を実装します。リポジトリインターフェースにJPQLを使ったメソッドを定義します。


package com.example.demo.repository;

import com.example.demo.entity.User;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.data.jpa.repository.JpaRepository;
import java.util.List;

public interface UserRepository extends JpaRepository<User, Long> {

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

}

@Queryアノテーションの中にJPQL文を記述します。ここでは、:nameの部分にメソッド引数nameがバインドされます。これにより、SQLを明示的に書かなくても、簡単に名前での検索が実現できます。

5. @Queryアノテーションを使ったJPQLの実行方法

Spring Data JPAでは、JPQLを@Queryアノテーションを使って記述することで、複雑な検索ロジックを簡単に記述できます。以下の例では、年齢が一定以上のユーザーを取得するクエリを記述しています。


@Query("SELECT u FROM User u WHERE u.age > :age")
List<User> findUsersOlderThan(@Param("age") int age);

このように、JPQL文はSQLとは異なり、Entityとそのプロパティを使って構築されます。JPQLの文法ミスがあると、実行時にエラーが発生するため、構文を正しく記述することが大切です。

コントローラ側では、リポジトリを使って簡単にJPQLクエリを呼び出すことができます。


@GetMapping("/users/older")
public String getOlderUsers(Model model) {
    List<User> users = userRepository.findUsersOlderThan(30);
    model.addAttribute("users", users);
    return "user-list";
}

userRepository.findUsersOlderThan(30)のように呼び出すことで、JPQLで条件に合うユーザーだけを取得できます。Thymeleafと組み合わせれば、取得したデータを画面に表示することも簡単にできます。

このように、@Queryアノテーションを使えば、SQLを直接書くことなく、簡潔にデータベース検索処理を記述できるのがSpring BootとJPQLの大きな魅力です。

6. JPQLでの注意点

JPQLは非常に便利なクエリ言語ですが、初心者がつまずきやすいポイントもあります。ここではJPQLの記述ミスや実行時に発生しやすいエラーについて解説します。

まず注意すべき点は、エンティティ名とフィールド名を正確に指定する必要があるということです。SQLではテーブル名やカラム名を使いますが、JPQLではJavaのクラス名とプロパティ名を使うため、少しでもスペルが違うとエラーになります。

例えば以下のように間違えるとエラーになります。


// 誤り："Users" は存在しないクラス名
@Query("SELECT u FROM Users u")

このような場合、実行時に「エンティティが見つかりません」などの例外が発生します。また、エンティティのプロパティに対する条件を記述する際も、実際のプロパティ名と一致していなければなりません。

もうひとつの注意点は、JPQLではネイティブSQLで使える関数や構文が使えないことがあるという点です。特定のデータベース依存の構文はJPQLではサポートされていないため、必要に応じてネイティブクエリに切り替える判断も必要です。

7. クエリメソッドとの使い分け

Spring Data JPAでは、JPQLの他にも「クエリメソッド」という機能を使ってデータ検索が可能です。クエリメソッドとは、メソッド名だけで検索条件を表現する書き方です。例えば、次のように定義できます。


List<User> findByName(String name);

このメソッドはnameプロパティが一致するUserを自動で検索します。Spring Bootがこのメソッド名から内部的にJPQLを組み立ててくれるため、簡単な検索であれば非常に便利です。

一方、複雑な条件や結合、サブクエリを使いたい場合は、@QueryアノテーションでJPQLを自分で記述する方が適しています。

つまり、

簡単な検索はクエリメソッド
複雑なロジックは@QueryによるJPQL

という使い分けが効果的です。これにより、保守性と柔軟性のバランスを取ることができます。

8. JPQLを使った簡単なアプリケーション例

最後に、JPQLを使った簡単なSpring Bootアプリケーションの例を紹介します。ここでは、年齢が指定された値以上のユーザーを一覧表示するアプリケーションを作成します。

まず、リポジトリにJPQLを使ったクエリメソッドを定義します。


@Query("SELECT u FROM User u WHERE u.age > :age")
List<User> findByMinAge(@Param("age") int age);

次に、コントローラでこのメソッドを呼び出し、検索結果を画面に渡します。


@Controller
public class UserController {

    private final UserRepository userRepository;

    public UserController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @GetMapping("/users/age")
    public String showUsersByAge(@RequestParam("age") int age, Model model) {
        List<User> users = userRepository.findByMinAge(age);
        model.addAttribute("users", users);
        return "user-list";
    }
}

最後に、表示用のHTMLテンプレートを用意します（Thymeleaf使用）。


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

このように、Spring BootとJPQLを使えば、Gradle＋Pleiades環境で簡単にMVC構成のアプリケーションを作成できます。初心者でも手順を追って学べば、十分に実用的なアプリを構築することが可能です。

まとめ

今回の記事では、Spring BootにおけるJPQL（Java Persistence Query Language）の基本概念から、リポジトリを使ったデータ取得方法、クエリの書き方までを詳しく解説しました。JPQLはSQLに似ていますが、テーブルではなくJavaのエンティティを操作するため、オブジェクト指向に沿ったクエリ記述が可能です。初心者にとって、SQLとの違いを理解することが最初のステップとなります。JPQLを使うことで、エンティティのプロパティを直接参照して検索、並び替え、条件付き取得などを柔軟に実装できます。

JPQLを活用するには、まずエンティティクラスを正しく定義し、@Entityや@Idなどのアノテーションでデータベースのテーブルに対応させることが重要です。また、JpaRepositoryを継承したリポジトリインターフェースを作成することで、JPQLクエリやクエリメソッドを簡単に呼び出せるようになります。@Queryアノテーションを活用すれば、複雑な検索条件や結合処理も簡潔に記述可能です。

JPQLでの注意点として、エンティティ名やフィールド名を正確に指定する必要があります。SQLのようにテーブル名やカラム名で操作するのではなく、Java側のクラス名やプロパティ名を間違えるとエラーが発生します。また、JPQLはデータベース依存の特殊関数が使えない場合があるため、複雑な処理が必要な場合はネイティブSQLの活用も検討しましょう。

JPQLのサンプルまとめ


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

@Query("SELECT u FROM User u WHERE u.age > :age")
List<User> findUsersOlderThan(@Param("age") int age);


List<User> findByName(String name);
List<User> findByAgeGreaterThan(int age);

クエリメソッドは簡単な検索に向き、@Queryアノテーションを使ったJPQLは複雑な条件や結合処理に向いています。用途に応じて使い分けることで、保守性の高いアプリケーション開発が可能になります。

実際のアプリケーション例としては、ユーザーの年齢や名前で条件を指定して一覧表示するWebアプリを簡単に構築できます。Thymeleafなどのテンプレートエンジンと組み合わせることで、画面表示も容易に行えるため、Spring Boot初心者でもJPQLを学びながら実務で使えるアプリを作成可能です。

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

新人

「JPQLはSQLと似ていますが、エンティティを対象にするんですね。テーブルではなくJavaのクラスを使うのがポイントだと理解しました。」

先輩

「その通り。エンティティのフィールド名を正確に指定することで、オブジェクト指向に沿った検索ができます。SQLのようにテーブルやカラムに縛られない点がJPQLの魅力です。」

新人

「@Queryアノテーションを使うと、複雑な条件でも簡潔に記述できるんですね。クエリメソッドと使い分けると効率的です。」

先輩

「そうだね。簡単な検索はクエリメソッド、複雑な検索や結合は@QueryでJPQLを書く。この使い分けを意識すると、コードが整理されて保守性も向上するよ。」

新人

「Spring Bootでリポジトリを作って、Thymeleafで画面表示までできれば、初心者でも簡単に実用的なアプリが作れるんですね。」

先輩

「そう。JPQLの基本を理解して、リポジトリやコントローラで適切に呼び出す練習を重ねれば、実務でもすぐに使えるスキルになるよ。」

この記事を読んだ人からの質問

JPQLとは？基本概念とクエリの書き方を完全解説！初心者でもわかるSpringデータベース操作