SpringのCriteriaBuilder equalメソッドの使い方を完全解説！初心者でもわかる等価条件とCriteria API

1. CriteriaBuilderとは何かを初心者向けに理解しよう

1. CriteriaBuilderとは何かを初心者向けに理解しよう

CriteriaBuilderは、JPAのCriteria APIを使ってデータベースへの問い合わせをJavaのコードで組み立てるためのインターフェースです。Spring BootやSpring Data JPAを使ってデータベース検索を学習していると、リポジトリのメソッドやJPQLなど、さまざまな検索方法が登場します。Criteria APIも、その中のひとつです。

Criteria APIの特徴は、検索条件をJava側で柔軟に作成できるところです。例えば、商品検索画面で利用者が商品名だけを入力した場合と、商品名とカテゴリの両方を入力した場合では、必要な検索条件が変わります。このような検索条件が状況によって変化する処理を、動的検索と呼ぶことがあります。

CriteriaBuilderには、検索条件を作成するためのさまざまなメソッドがあります。その中でもequalは、二つの値が等しいことを条件として表す基本的なメソッドです。商品状態、カテゴリ、会員区分、都道府県、注文状態など、特定の値と一致するデータを検索するときに利用できます。

2. equalメソッドとは何をするメソッドなのか

2. equalメソッドとは何をするメソッドなのか

CriteriaBuilderのequalメソッドは、指定した項目と値が等しいという条件を作るために利用します。例えば、商品データの状態が販売中と一致するものだけを検索したい場合や、会員の都道府県が大阪府と一致するものだけを検索したい場合に使えます。

Criteria APIでは、検索条件をPredicateという形で表します。equalを使うと、このPredicateを作ることができます。そのPredicateをCriteriaQueryのwhereに設定することで、実際の検索条件として利用できます。

CriteriaBuilder cb = entityManager.getCriteriaBuilder();
CriteriaQuery<Product> query = cb.createQuery(Product.class);
Root<Product> root = query.from(Product.class);

Predicate condition = cb.equal(root.get("status"), "ACTIVE");

query.select(root);
query.where(condition);

List<Product> products = entityManager.createQuery(query).getResultList();

この例では、商品を表すProductエンティティのstatusが販売中を表す値と等しいデータだけを検索しています。root.getで検索対象の項目を指定し、equalで比較する値を指定しています。

初心者は、equalそのものが検索を実行するメソッドではないことも覚えておきましょう。equalはあくまで等しいという検索条件を作成します。その条件をwhereへ設定し、最後にEntityManagerから問い合わせを実行することで検索結果を取得します。

3. equalとwhereを組み合わせる基本的な検索方法

3. equalとwhereを組み合わせる基本的な検索方法

CriteriaBuilderのequalを利用するときは、whereと組み合わせる形が基本になります。equalによって作成した条件をwhereへ設定すると、その条件に一致するデータだけが検索対象になります。

例えば、会員データの都道府県が大阪府である利用者だけを検索する場合を考えてみましょう。このような完全一致による検索は、equalが分かりやすく活用できる代表的な場面です。

public List<User> findByPrefecture(String prefecture) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<User> query = cb.createQuery(User.class);
    Root<User> root = query.from(User.class);

    query.select(root);
    query.where(cb.equal(root.get("prefecture"), prefecture));

    return entityManager.createQuery(query).getResultList();
}

このメソッドでは、引数として受け取った都道府県と、利用者エンティティの都道府県が一致するデータを検索しています。呼び出し側から大阪府を渡せば大阪府の利用者を検索し、東京都を渡せば東京都の利用者を検索できます。

このように検索する値を変数として受け取れるため、Spring Bootの検索フォームとの相性もよいです。利用者が画面から選択した値を受け取り、その値をCriteriaBuilderのequalに渡して検索条件を作成できます。

完全一致検索は、カテゴリ、状態、会員種別、地域、権限など、あらかじめ決められた値から選択する項目で特に使いやすい方法です。

4. 文字列や数値をequalで比較する方法

4. 文字列や数値をequalで比較する方法

CriteriaBuilderのequalでは、文字列だけでなく、数値などさまざまな値を比較できます。例えば商品カテゴリのような文字列を比較することもできますし、商品価格や年齢などの数値を比較することもできます。

次の例では、指定された価格と完全に一致する商品だけを検索しています。

public List<Product> findByPrice(Integer price) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    Predicate condition = cb.equal(root.get("price"), price);

    query.select(root);
    query.where(condition);

    return entityManager.createQuery(query).getResultList();
}

この場合、商品価格が指定された値と同じデータだけが取得されます。例えば価格として千円を指定すれば、価格が千円の商品だけが検索対象になります。

ただし、価格検索では完全一致だけでなく、指定価格以上や指定価格以下といった検索が必要になることもあります。その場合にはequalではなく、大小関係を表す別のCriteriaBuilderのメソッドを利用します。equalは、あくまで同じ値であることを条件にしたい場合に使うと覚えておきましょう。

5. 複数のequal条件をandで組み合わせる方法

5. 複数のequal条件をandで組み合わせる方法

実際のSpring BootによるWebアプリケーションでは、検索条件が一つだけとは限りません。例えば、商品カテゴリが食品で、さらに販売状態が販売中の商品を検索したい場合があります。このような場合には、複数のequal条件を作り、andで組み合わせることができます。

public List<Product> findProducts(String category, String status) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    Predicate categoryCondition =
        cb.equal(root.get("category"), category);

    Predicate statusCondition =
        cb.equal(root.get("status"), status);

    query.select(root);
    query.where(cb.and(categoryCondition, statusCondition));

    return entityManager.createQuery(query).getResultList();
}

ここでは、カテゴリが一致する条件と状態が一致する条件をそれぞれPredicateとして作っています。そして、CriteriaBuilderのandを使って、二つの条件を両方とも満たすデータだけを検索しています。

検索条件が増えてきたときは、一つの長い式として書くよりも、Predicateを条件ごとに分けると内容を理解しやすくなります。商品カテゴリの条件、販売状態の条件、地域の条件など、役割ごとに分けておけば、後から検索条件を追加するときにも整理しやすくなります。

Spring Data JPAで複雑な検索画面を作る場合には、このPredicateとequalの組み合わせが重要になります。利用者が入力した項目によって必要なPredicateだけを追加していくことで、動的検索へ発展させることができます。

6. equalを使った動的検索の考え方

6. equalを使った動的検索の考え方

CriteriaBuilderが便利な理由のひとつは、検索条件を動的に変更できることです。例えば商品検索画面にカテゴリと状態の入力欄がある場合、利用者がカテゴリだけを指定することもあれば、カテゴリと状態の両方を指定することもあります。

固定された検索であれば、最初からすべての条件を記述できます。しかし、入力された項目だけを条件として利用したい場合には、Criteria APIを使って必要な条件だけを追加する方法が便利です。

public List<Product> search(String category, String status) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    List<Predicate> conditions = new ArrayList<>();

    if (category != null && !category.isEmpty()) {
        conditions.add(cb.equal(root.get("category"), category));
    }

    if (status != null && !status.isEmpty()) {
        conditions.add(cb.equal(root.get("status"), status));
    }

    query.select(root);
    query.where(conditions.toArray(new Predicate[0]));

    return entityManager.createQuery(query).getResultList();
}

この例では、カテゴリが入力されている場合だけカテゴリのequal条件を追加し、状態が入力されている場合だけ状態のequal条件を追加しています。両方とも入力されていれば二つの条件が設定され、どちらも入力されていなければ条件を追加しない形になります。

このような処理は、Spring Bootの検索フォームでよく使われます。検索項目が増えても、一つずつ条件を追加できるため、利用者の入力内容に合わせた柔軟な検索機能を作成できます。

CriteriaBuilderのequalを学ぶときは、単純な完全一致検索だけで終わらず、入力された値がある場合だけ検索条件を追加するという動的検索の考え方まで理解しておくと、実際のWebアプリケーション開発へ応用しやすくなります。

7. equalとlikeの違いを初心者向けに理解しよう

7. equalとlikeの違いを初心者向けに理解しよう

CriteriaBuilderによる文字列検索では、equalと似た場面でlikeというメソッドも登場します。この二つは検索方法が異なるため、目的に応じて使い分ける必要があります。

equalは、値が同じであることを条件にする完全一致検索です。例えばカテゴリが食品と完全に一致する商品や、注文状態が発送済みと一致する注文を検索するときに向いています。

一方、likeは文字列の一部分が一致するデータを検索したい場合に利用します。例えば商品名にパソコンという文字が含まれる商品を探すような部分一致検索では、equalよりもlikeが適しています。

検索条件を作るときは、単に文字列を検索したいからequalを使うのではなく、完全に同じ値を探したいのか、一部分だけ一致すればよいのかを考えることが大切です。この違いを理解しておくと、Spring Bootの検索画面で期待した結果が得られない原因を減らすことができます。

8. equalを使うときに初心者が注意したいポイント

8. equalを使うときに初心者が注意したいポイント

CriteriaBuilderのequalを使って検索しても期待した結果にならない場合は、いくつかの確認ポイントがあります。まず確認したいのは、root.getで指定している属性名です。ここではデータベースの列名ではなく、基本的にはエンティティ側で定義している属性名を指定します。

例えばデータベース上の列名とJavaのフィールド名が異なる場合、データベースの列名をそのまま指定すると意図した検索にならない可能性があります。Criteria APIではエンティティを基準として問い合わせを組み立てるという考え方を覚えておきましょう。

次に、比較する値の型にも注意します。数値の項目に文字列を渡すなど、エンティティの属性と比較値の種類が合っていないと、エラーや意図しない動作につながる可能性があります。文字列の項目なら文字列、数値の項目なら対応する数値型というように、型を意識して扱うことが重要です。

また、文字列の完全一致では、入力された文字列の内容そのものにも注意が必要です。利用者が入力した値に余分な空白が含まれていると、見た目が同じように見えても完全一致にならないことがあります。検索フォームから受け取る値を使う場合には、入力値の扱いも確認しましょう。

初心者のうちは検索結果がゼロ件になるとequalに問題があると思いやすいですが、原因は属性名や比較値、検索方法の選択にあることも少なくありません。一つずつ確認することで原因を見つけやすくなります。

9. Spring Bootでequalを活用できる実践的な場面

9. Spring Bootでequalを活用できる実践的な場面

CriteriaBuilderのequalは非常に基本的なメソッドですが、Spring BootとSpring Data JPAを使った実際のWebアプリケーションでは幅広く利用できます。特に、決められた選択肢の中から値を指定する検索画面との相性がよいです。

例えば商品管理システムでは、カテゴリが家電の商品だけを検索したり、販売状態が販売中の商品だけを表示したりできます。会員管理システムでは、会員区分や都道府県などを指定した検索に利用できます。注文管理システムでは、注文状態が受付済み、発送済み、完了などの特定の状態に一致する注文だけを検索できます。

さらに、equalで作成した検索条件は、一覧検索だけではなく件数取得にも活用できます。例えば販売中の商品が何件あるのかを取得したい場合には、equalによって販売状態の条件を作り、その条件をCriteriaBuilderのcountを使った問い合わせへ適用できます。

このように、CriteriaBuilderの各メソッドは単独で覚えるよりも、組み合わせて理解することが重要です。equalで一致条件を作成し、whereで条件を設定し、andで複数条件を組み合わせたり、countで条件に一致する件数を取得したりすることで、より実践的なデータベース検索を作成できます。

Spring BootでCriteria APIを学習するときは、まず一つのequal条件による完全一致検索から始めるとよいでしょう。その後、二つのequal条件をandで組み合わせ、さらに入力された値がある場合だけPredicateを追加する動的検索へ進むと、CriteriaBuilderの役割を理解しやすくなります。

CriteriaBuilderは、最初は記述が多く複雑に見えるかもしれません。しかし、CriteriaBuilderは条件を作るもの、CriteriaQueryは問い合わせ全体を表すもの、Rootは検索対象となるエンティティ、Predicateは検索条件、equalは等しいという条件を作るメソッドというように、それぞれの役割を分けて考えると理解しやすくなります。

Spring BootやJPAで検索画面、管理画面、商品検索、会員検索、予約検索などを実装するとき、完全一致による検索は基本となる処理です。CriteriaBuilderのequalを理解しておけば、単純な検索から複数条件の検索、動的検索、条件付き件数取得まで段階的に発展させることができます。

まとめ

まとめ

Spring BootやSpring Data JPAを使ってデータベース検索を作成するとき、検索条件を柔軟に組み立てたい場面ではCriteriaBuilderが役立ちます。今回学習したequalメソッドは、エンティティの属性と指定した値が等しいという条件を作成するための基本的なメソッドです。商品カテゴリ、販売状態、会員区分、都道府県、注文状態など、決められた値と完全に一致するデータを検索したいときに利用できます。

CriteriaBuilderはSpringだけに用意されている機能ではなく、JPAのCriteria APIで利用するインターフェースです。Criteria APIでは、SQLを文字列として直接組み立てるのではなく、Javaのコードを使って問い合わせや検索条件を作成します。そのため、利用者が入力した条件に応じて検索内容を変化させる動的検索との相性がよく、Spring Bootで検索フォームや管理画面を作るときにも活用できます。

CriteriaBuilderとequalの基本的な役割

Criteria APIを初めて見ると、CriteriaBuilder、CriteriaQuery、Root、Predicateなど複数の名前が登場するため、難しく感じるかもしれません。しかし、それぞれの役割を分けて考えると理解しやすくなります。

CriteriaBuilderは検索条件や問い合わせに必要な式を作るための道具です。CriteriaQueryは問い合わせ全体の形を表し、Rootはどのエンティティを検索の出発点にするのかを表します。そしてPredicateは検索条件を表します。equalは、そのPredicateを作るために利用できるメソッドのひとつです。

CriteriaBuilder cb = entityManager.getCriteriaBuilder();
CriteriaQuery<Product> query = cb.createQuery(Product.class);
Root<Product> root = query.from(Product.class);

Predicate condition = cb.equal(root.get("status"), "ACTIVE");

query.select(root);
query.where(condition);

List<Product> products = entityManager.createQuery(query).getResultList();

この基本形では、商品を表すエンティティの状態が指定した値と完全に一致するデータだけを検索しています。equalが行っているのは検索そのものではなく、等しいという条件を作ることです。作成した条件をwhereへ設定し、最後にEntityManagerを使って問い合わせを実行することで検索結果を取得します。

Spring初心者がCriteriaBuilderのequalを学ぶときは、equalだけを単独で覚えるのではなく、Rootで項目を指定し、equalで条件を作り、whereへ設定し、問い合わせを実行するという一連の流れで覚えることが大切です。

equalは完全一致検索に向いている

CriteriaBuilderのequalは、値が同じであることを条件にする完全一致検索で利用します。例えば、都道府県が大阪府である会員を検索する、商品カテゴリが家電である商品だけを検索する、注文状態が発送済みである注文だけを取得するといった処理に向いています。

public List<User> findByPrefecture(String prefecture) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<User> query = cb.createQuery(User.class);
    Root<User> root = query.from(User.class);

    query.select(root);
    query.where(cb.equal(root.get("prefecture"), prefecture));

    return entityManager.createQuery(query).getResultList();
}

この例では、メソッドの引数として受け取った都道府県と、会員エンティティの都道府県が等しいデータだけを検索しています。検索する値を固定する必要はなく、画面から受け取った値やメソッドの引数をequalへ渡すことができます。そのため、Spring Bootの検索フォームから選択されたカテゴリや状態を検索条件として利用する処理にも応用できます。

equalは文字列だけでなく、数値などの比較にも利用できます。ただし、数値を検索するときでも、完全に同じ値を探す場合に使うという考え方は変わりません。価格が指定金額以上、年齢が指定値以下といった大小関係を検索したい場合には、目的に合った別のCriteriaBuilderのメソッドを使います。

複数のequal条件はandで組み合わせられる

実際のSpring Bootによるデータベース検索では、一つの条件だけでなく、複数の条件を同時に指定することがあります。例えば、商品カテゴリが食品であり、さらに販売状態が販売中の商品だけを取得したい場合です。このようなときは、それぞれのequal条件をPredicateとして作成し、andを使って組み合わせることができます。

public List<Product> findProducts(String category, String status) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    Predicate categoryCondition =
        cb.equal(root.get("category"), category);

    Predicate statusCondition =
        cb.equal(root.get("status"), status);

    query.select(root);
    query.where(cb.and(categoryCondition, statusCondition));

    return entityManager.createQuery(query).getResultList();
}

このように条件ごとにPredicateを分けておくと、どの条件が何を表しているのか読み取りやすくなります。検索条件が増えたときにも、カテゴリの条件、状態の条件、地域の条件というように整理できます。Spring Data JPAを使った実務的な検索処理では、条件を分かりやすく管理することも重要です。

andで組み合わせた場合は、指定した条件をすべて満たすデータが検索対象になります。条件の組み合わせを理解すると、商品検索、会員検索、予約検索、注文検索など、複数の検索項目を持つ画面にも応用できるようになります。

動的検索では必要なequal条件だけを追加する

CriteriaBuilderが特に便利なのは、検索条件を動的に組み立てたい場合です。例えば商品検索画面にカテゴリと販売状態の入力欄があっても、利用者が必ず両方を入力するとは限りません。カテゴリだけ指定する場合もあれば、販売状態だけ指定する場合、両方指定する場合もあります。

このような検索では、入力されている項目だけequalによるPredicateを追加する方法が使えます。利用者が入力していない項目まで無理に検索条件へ含める必要がないため、柔軟な検索画面を作成できます。

public List<Product> search(String category, String status) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    List<Predicate> conditions = new ArrayList<>();

    if (category != null && !category.isEmpty()) {
        conditions.add(cb.equal(root.get("category"), category));
    }

    if (status != null && !status.isEmpty()) {
        conditions.add(cb.equal(root.get("status"), status));
    }

    query.select(root);
    query.where(conditions.toArray(new Predicate[0]));

    return entityManager.createQuery(query).getResultList();
}

この考え方を理解すると、検索条件が三つ、四つと増えた場合にも対応しやすくなります。検索条件が入力されているかを確認し、必要なPredicateだけを追加していくことで、Spring Bootの動的検索を組み立てられます。

CriteriaBuilderのequalは単純な完全一致検索のためのメソッドですが、Predicateと組み合わせることで、実際のWebアプリケーションに必要な柔軟な検索機能へ発展させられます。

equalとlikeを目的に応じて使い分ける

文字列検索を作るときには、equalとlikeの違いも理解しておく必要があります。equalは値が完全に一致することを条件にするのに対して、likeは文字列の一部分が一致する検索で利用します。

例えば商品カテゴリが家電と完全に一致する商品を検索するならequalが向いています。一方で、商品名にパソコンという文字が含まれている商品を検索するのであれば、部分一致検索が必要になるためlikeを検討します。

検索結果がゼロ件になる場合は、equalの書き方だけでなく、本当に完全一致検索が目的なのかも確認するとよいでしょう。部分一致を期待しているのにequalを使っていれば、利用者が期待する検索結果にならないことがあります。

検索結果が取得できないときの確認ポイント

CriteriaBuilderのequalを使っているのに検索結果が取得できない場合は、まずRootで正しいエンティティを指定しているか確認します。次に、root.getへ指定した属性名を確認します。Criteria APIではエンティティを基準として問い合わせを作るため、基本的にはJava側のエンティティに定義された属性名を指定します。

比較する値の型にも注意が必要です。数値の属性へ文字列を比較しようとするなど、属性と比較値の種類が合っていない場合は、意図した検索にならない原因になります。また、検索フォームから受け取った文字列に余分な空白が含まれていると、完全一致にならない場合もあります。

エラーにならず検索結果だけがゼロ件になる場合は、検索条件の内容を一つずつ確認するのが効果的です。最初はequal条件を一つだけにして検索し、正しく取得できることを確認してから、二つ目、三つ目の条件を追加すると原因を切り分けやすくなります。

countなど他のCriteriaBuilderメソッドにも応用できる

equalで作成したPredicateは、一覧を取得する検索だけでなく、条件に一致するデータ件数を取得する処理にも利用できます。例えば販売中の商品一覧を取得すると同時に、販売中の商品が全部で何件あるのかを表示したい場合があります。

そのような場合には、equalで販売状態の検索条件を作成し、件数取得用の問い合わせにも同じ条件を設定できます。CriteriaBuilderのcountと組み合わせれば、検索条件に一致するデータの総件数を取得できます。

public long countActiveProducts() {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Long> query = cb.createQuery(Long.class);
    Root<Product> root = query.from(Product.class);

    Predicate condition =
        cb.equal(root.get("status"), "ACTIVE");

    query.select(cb.count(root));
    query.where(condition);

    return entityManager.createQuery(query).getSingleResult();
}

このようにCriteriaBuilderのメソッドは、それぞれを別々に暗記するよりも、組み合わせながら理解すると実践的な使い方が見えてきます。equalで一致条件を作り、whereへ設定する。複数条件ならandでまとめる。件数が必要ならcountと組み合わせるというように、目的に応じて機能を組み立てていきます。

Spring BootでJPAのCriteria APIを学習するときは、最初に一つのequal条件による完全一致検索を作成し、次に複数のequal条件、その後に動的検索へ進むと理解しやすくなります。さらにlikeやcountなどのメソッドとの違いや組み合わせまで理解できれば、検索画面、商品管理、会員管理、予約管理、注文管理、ページングなど、さまざまなデータベース処理へ応用できます。

CriteriaBuilderはコード量が多く見えるため、最初は難しい印象を持ちやすい機能です。しかし、CriteriaBuilderは条件を作るためのもの、CriteriaQueryは問い合わせを表すもの、Rootは検索対象、Predicateは検索条件、equalは値が等しいという条件を作るものというように役割を整理すれば、処理の流れを追いやすくなります。Spring初心者は、短い検索から少しずつ条件を増やしながら確認すると、Criteria APIを無理なく理解できます。