SpringのCriteriaBuilder likeメソッドの使い方を完全解説！初心者でもわかる部分一致検索とCriteria API

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

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

CriteriaBuilderは、JPAのCriteria APIを使ってデータベースへの問い合わせや検索条件をJavaのコードで組み立てるためのインターフェースです。Spring BootやSpring Data JPAを使ったデータベース処理では、リポジトリのメソッドやJPQLなどと並んで、柔軟な検索を作成する方法としてCriteria APIを利用できます。

Criteria APIの大きな特徴は、検索条件をJava側で組み立てられることです。例えば、商品検索画面で商品名、カテゴリ、販売状態など複数の検索項目があり、利用者が入力した項目だけを検索条件として使いたい場合があります。このように状況によって検索条件が変化する処理は、動的検索と呼ばれます。

CriteriaBuilderには、検索条件を作るためのさまざまなメソッドがあります。指定した値と完全に一致する条件を作るequalや、文字列のパターンを使った検索条件を作るlikeなどがあります。今回学習するlikeは、商品名、会員名、住所、タイトルなどの文字列検索で特に役立つメソッドです。

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

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

CriteriaBuilderのlikeメソッドは、文字列が指定したパターンに一致するかどうかを表す検索条件を作成するために利用します。完全に同じ文字列だけではなく、文字列の先頭、末尾、途中などが一致するデータを検索したいときに便利です。

例えば、商品名にパソコンという文字が含まれている商品を検索したい場合を考えてみましょう。商品名がノートパソコンでも、ゲーミングパソコンでも、パソコンケースでも、指定した文字を含んでいれば検索対象にできます。

Criteria APIでは、likeによって作成された検索条件はPredicateとして扱われます。そのPredicateをCriteriaQueryのwhereに設定し、EntityManagerから問い合わせを実行することで、条件に一致したデータを取得します。

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

Predicate condition =
    cb.like(root.get("name"), "%パソコン%");

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

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

この例では、商品名の中にパソコンという文字列が含まれている商品を検索しています。likeの検索では、パーセント記号をワイルドカードとして利用することで、文字列の一部分が一致するデータを探せます。

初心者が覚えておきたいのは、likeそのものが検索を実行するわけではないことです。likeは検索条件を作るためのメソッドであり、作成した条件をwhereに設定してから問い合わせを実行します。

3. 部分一致検索で使うワイルドカードを理解しよう

3. 部分一致検索で使うワイルドカードを理解しよう

CriteriaBuilderのlikeを使ううえで重要なのがワイルドカードです。ワイルドカードとは、任意の文字列などを表すために使う特別な記号です。likeによる検索では、パーセント記号を使うことで、文字列の前後にどのような文字があってもよいという条件を作れます。

例えば、検索文字としてJavaを指定し、その前後にパーセント記号を付けると、文字列の途中にJavaが含まれているデータを検索できます。このような検索を部分一致検索と呼びます。

ワイルドカードをどこに付けるかによって検索方法が変わります。検索文字の後ろだけに付けると前方一致、検索文字の前だけに付けると後方一致、前後の両方に付けると部分一致になります。

Spring Bootで検索画面を作る場合は、どの検索方法が利用者にとって自然なのかを考えることが大切です。商品名や氏名などは部分一致、商品コードや特定の分類名などは完全一致というように、検索対象によって適した方法が異なります。

4. 前方一致と後方一致と部分一致の書き方

4. 前方一致と後方一致と部分一致の書き方

CriteriaBuilderのlikeでは、ワイルドカードの位置を変えることで前方一致、後方一致、部分一致を使い分けることができます。Spring Bootの検索機能を作るときには、この違いを理解しておくとさまざまな検索画面に対応できます。

まず前方一致は、指定した文字列から始まるデータを検索する方法です。例えば、商品名がJavaで始まるデータを探したい場合に利用できます。

public List<Product> searchStartsWith(String keyword) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    query.select(root);
    query.where(
        cb.like(root.get("name"), keyword + "%")
    );

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

後方一致では、検索文字列の前側にワイルドカードを付けます。これにより、指定した文字列で終わるデータを検索できます。書籍タイトルや商品名の末尾が特定の言葉で終わっているデータを探したい場合などに利用できます。

public List<Product> searchEndsWith(String keyword) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    query.select(root);
    query.where(
        cb.like(root.get("name"), "%" + keyword)
    );

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

部分一致では、検索文字列の前後にワイルドカードを付けます。この方法は、検索文字がどこに含まれていてもよいため、一般的なキーワード検索で利用しやすい方法です。

public List<Product> searchContains(String keyword) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    query.select(root);
    query.where(
        cb.like(root.get("name"), "%" + keyword + "%")
    );

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

検索フォームで利用者が自由にキーワードを入力する場合には、前後にワイルドカードを付けた部分一致検索が使われることがあります。一方、検索目的によっては前方一致のほうが適している場合もあるため、何を探したい画面なのかを考えて選びましょう。

5. equalとlikeの違いを理解して使い分けよう

5. equalとlikeの違いを理解して使い分けよう

CriteriaBuilderを学習すると、equalとlikeのどちらを使えばよいのか迷うことがあります。この二つはどちらも検索条件を作るメソッドですが、目的が異なります。

equalは完全一致検索に利用します。例えば商品カテゴリが家電と完全に一致するデータや、注文状態が発送済みと一致するデータを検索する場合に向いています。

一方、likeは文字列のパターン検索に利用します。商品名にパソコンが含まれる、氏名に田中が含まれる、記事タイトルにSpringが含まれるといった検索ではlikeが便利です。

例えば商品検索画面にカテゴリと商品名の二つの検索項目がある場合、カテゴリにはequal、商品名にはlikeを使うという組み合わせが考えられます。すべての文字列検索にlikeを使うのではなく、完全一致が必要なのか部分一致が必要なのかを判断して使い分けることが重要です。

検索結果が多すぎる場合は部分一致の条件が広すぎる可能性があり、逆に検索結果が見つからない場合は完全一致を使っていることが原因かもしれません。検索対象の性質を考えてメソッドを選ぶことで、利用しやすい検索機能を作れます。

6. likeを使った動的検索の作り方

6. likeを使った動的検索の作り方

Spring Bootで商品検索や会員検索を作る場合、利用者が必ず検索キーワードを入力するとは限りません。キーワードが入力されている場合だけlike条件を追加し、未入力の場合はその条件を使わないという処理が必要になることがあります。

このように、入力された内容によって検索条件を追加したり外したりする処理が動的検索です。CriteriaBuilderはJavaのコードでPredicateを追加できるため、動的検索と相性がよい仕組みです。

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

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

    if (keyword != null && !keyword.isEmpty()) {
        conditions.add(
            cb.like(root.get("name"), "%" + keyword + "%")
        );
    }

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

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

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

この例では、商品名のキーワードが入力されている場合だけlikeによる部分一致条件を追加し、カテゴリが指定されている場合だけequalによる完全一致条件を追加しています。

例えばキーワードだけが入力されていれば商品名だけで検索し、カテゴリだけが選択されていればカテゴリだけで検索します。両方が指定されていれば二つの条件を使った検索になります。この方法を発展させれば、価格、販売状態、地域など複数の検索条件を持つ画面にも対応できます。

Spring Data JPAで複雑な検索フォームを作る場合、検索条件をPredicateとして一つずつ追加する考え方を理解しておくと便利です。likeはその中でも自由入力のキーワード検索で利用しやすいメソッドです。

7. 大文字と小文字を意識したlike検索

7. 大文字と小文字を意識したlike検索

英字を含む文字列をlikeで検索するときには、大文字と小文字の扱いにも注意が必要です。データベースや設定によって文字列比較の扱いが異なる場合があるため、大文字と小文字を区別せずに検索したいときは、検索対象と検索キーワードの両方を同じ形式にそろえる方法があります。

CriteriaBuilderには、文字列を小文字へ変換するためのlowerや、大文字へ変換するためのupperがあります。例えば、検索対象を小文字へ変換し、入力されたキーワードも小文字へ変換してからlikeで比較する方法があります。

public List<Product> searchIgnoreCase(String keyword) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    String pattern = "%" + keyword.toLowerCase() + "%";

    query.select(root);
    query.where(
        cb.like(cb.lower(root.get("name")), pattern)
    );

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

この方法では、エンティティ側の商品名を小文字として比較し、検索キーワードも小文字にしているため、大文字と小文字の違いを意識した検索を作りやすくなります。

日本語だけを扱う検索では大文字と小文字を意識する場面は少ないですが、商品名、技術名、メールアドレス、英語タイトルなどを検索する機能では考慮したいポイントです。

8. ワイルドカードを含む入力値を扱うときの注意点

8. ワイルドカードを含む入力値を扱うときの注意点

CriteriaBuilderのlikeでは、パーセント記号などが検索パターンとして特別な意味を持ちます。そのため、利用者が入力した検索キーワードそのものにワイルドカードとして扱われる文字が含まれている場合には注意が必要です。

例えば、利用者が記号そのものを検索したいのに、その文字がlikeの検索パターンとして解釈されると、想定していた検索条件とは異なる結果になる可能性があります。検索画面で自由入力を受け付ける場合は、どのような文字を検索対象として認めるのかを考えておく必要があります。

CriteriaBuilderのlikeには、エスケープ文字を指定できる形式も用意されています。エスケープ文字とは、本来は特別な意味を持つ文字を通常の文字として扱いたい場合に利用するものです。

初心者の段階では、まず前方一致、後方一致、部分一致という基本的なlike検索を理解しておけば十分です。そのうえで、検索フォームから自由な文字列を受け取る実践的なアプリケーションを作るときには、ワイルドカード文字やエスケープ処理についても確認していきましょう。

9. likeで検索できないときの確認ポイントと実践的な使い方

9. likeで検索できないときの確認ポイントと実践的な使い方

CriteriaBuilderのlikeを使っているのに期待した検索結果が取得できない場合は、いくつかの項目を順番に確認すると原因を見つけやすくなります。

最初に確認したいのは、Rootで正しいエンティティを指定しているかという点です。次に、root.getで指定している属性名を確認します。Criteria APIでは基本的にデータベースの列名ではなく、エンティティに定義された属性を基準として検索条件を作成します。

次に確認したいのがワイルドカードです。商品名のどこかに検索文字が含まれていればよいのに、検索文字の後ろだけにワイルドカードを付けていると、前方一致として検索されます。部分一致が目的なら検索キーワードの前後にワイルドカードを付ける必要があります。

また、検索フォームから取得したキーワードが空文字列になっていないかも確認しましょう。動的検索の場合は、キーワードが入力されているときだけlike条件を追加する形にすると処理を整理しやすくなります。

完全一致で十分な項目にlikeを使っていないかも確認することが大切です。例えば販売状態や会員区分のように選択肢が決まっている項目はequalが分かりやすく、商品名やタイトルのように一部分から探したい項目はlikeが向いています。

Spring Bootの実際のWebアプリケーションでは、商品検索、会員検索、記事検索、予約検索、管理画面などでlikeによる文字列検索を利用できます。商品名の一部から商品を探したり、会員名の一部から対象者を検索したり、記事タイトルに指定したキーワードが含まれているデータを検索したりする処理に応用できます。

さらに、likeで作成したPredicateは他の検索条件と組み合わせられます。商品名はlikeによる部分一致、カテゴリはequalによる完全一致、販売状態もequalによる完全一致というように、項目ごとに適した検索方法を選べます。

CriteriaBuilderを使った検索では、すべての条件を一つの方法で処理する必要はありません。文字列の部分一致ならlike、完全一致ならequalというように、検索内容によってメソッドを使い分けます。検索条件をPredicateとして整理しておけば、あとから条件が追加された場合にも対応しやすくなります。

Spring BootやSpring Data JPAでCriteria APIを学習するときは、まず一つの商品名を対象にした部分一致検索を作り、その後に前方一致や後方一致を試すと理解しやすくなります。次にequalとの組み合わせや、利用者が入力した条件だけを追加する動的検索へ進むと、実際の検索画面で使える知識につながります。

CriteriaBuilderは最初はコード量が多く見えますが、それぞれの役割を分けて考えることがポイントです。CriteriaBuilderは検索条件を作るためのもの、CriteriaQueryは問い合わせ全体を表すもの、Rootは検索対象となるエンティティ、Predicateは検索条件、likeは文字列のパターンに一致する条件を作るメソッドと整理すると理解しやすくなります。

likeによる部分一致検索を理解しておけば、Spring Bootで利用者が使いやすい検索フォームを作りやすくなります。商品名、氏名、住所、タイトルなど、入力されたキーワードから関連するデータを探したい場面は多いため、CriteriaBuilderのlikeはCriteria APIを学ぶうえで覚えておきたい基本的なメソッドのひとつです。

まとめ

まとめ

Spring BootやSpring Data JPAを使ってデータベース検索を実装するとき、商品名や氏名、住所、記事タイトルなどの一部分をキーワードとして検索したい場面があります。そのような文字列検索で役立つのが、JPAのCriteria APIに用意されているCriteriaBuilderのlikeメソッドです。likeを利用すると、完全に同じ文字列だけを探すのではなく、指定した文字列から始まるデータ、指定した文字列で終わるデータ、指定した文字列を途中に含むデータなどを検索できます。

CriteriaBuilderは、検索条件や問い合わせに必要な式をJavaのコードで組み立てるためのインターフェースです。Spring独自の機能ではなく、JPAのCriteria APIとして提供されています。Spring BootでJPAを利用するWebアプリケーションでは、検索フォームの入力内容によって条件が変わる動的検索を実装するときにも活用できます。

Criteria APIでは、CriteriaBuilderだけを使って検索するわけではありません。CriteriaQueryで問い合わせ全体の形を作り、Rootで検索対象となるエンティティを指定し、Predicateとして検索条件を作成します。そして、作成したPredicateをwhereへ設定し、EntityManagerから問い合わせを実行します。この一連の流れを理解すると、CriteriaBuilderのlikeがどの部分を担当しているのか分かりやすくなります。

likeを使った部分一致検索の基本

CriteriaBuilderのlikeを利用するときに重要なのが、ワイルドカードの使い方です。ワイルドカードを検索文字列の前後に付けることで、その文字列がどこかに含まれているデータを検索できます。商品検索画面で利用者が入力したキーワードを商品名の途中から探したい場合などに便利です。

public List<Product> searchByName(String keyword) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    Predicate condition =
        cb.like(root.get("name"), "%" + keyword + "%");

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

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

この処理では、商品名のどこかに検索キーワードが含まれている商品を取得します。例えば検索キーワードとしてパソコンを指定した場合、ノートパソコン、ゲーミングパソコン、パソコンケースなど、対象となる文字列を含んだ商品名を検索できます。

likeそのものがデータベースへの問い合わせを実行するわけではない点も重要です。likeは文字列の検索パターンに一致するという条件を作るメソッドです。作成した条件をwhereに設定し、最後に問い合わせを実行することで検索結果を取得します。

前方一致と後方一致と部分一致を使い分ける

likeによる検索では、ワイルドカードを付ける位置によって検索方法が変わります。検索キーワードの後ろだけにワイルドカードを付けると前方一致になり、指定した文字列から始まるデータを検索できます。検索キーワードの前だけに付けると後方一致となり、指定した文字列で終わるデータを検索できます。前後の両方に付けると部分一致となります。

public List<Product> searchStartsWith(String keyword) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    query.select(root);
    query.where(
        cb.like(root.get("name"), keyword + "%")
    );

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

前方一致は、商品名やタイトルが特定の文字列から始まるデータを探したいときに利用できます。一方、自由入力による一般的なキーワード検索では、前後にワイルドカードを付ける部分一致が使いやすい場合があります。

Spring Bootで検索機能を作るときには、何でも部分一致にすればよいわけではありません。利用者がどのような検索を期待しているのかを考え、前方一致、後方一致、部分一致を適切に選択することが大切です。

equalとlikeは検索目的によって使い分ける

CriteriaBuilderには、likeと一緒に覚えておきたいequalというメソッドがあります。equalは完全一致の条件を作成し、likeは文字列のパターンを使った検索条件を作成します。この違いを理解しておくと、Spring Data JPAで検索画面を実装するときに適切な検索方法を選びやすくなります。

例えば商品カテゴリが家電であるデータだけを検索したい場合は、カテゴリ名が完全に一致すればよいためequalが適しています。一方、商品名にパソコンという文字が含まれている商品を探したい場合はlikeによる部分一致検索が向いています。

商品検索画面では、商品名にはlike、カテゴリにはequal、販売状態にもequalというように、複数の検索方法を組み合わせることができます。CriteriaBuilderの各メソッドを個別に覚えるだけでなく、検索する項目の性質に応じて使い分けることが重要です。

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

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

    if (keyword != null && !keyword.isEmpty()) {
        conditions.add(
            cb.like(root.get("name"), "%" + keyword + "%")
        );
    }

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

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

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

この例では、検索キーワードが入力されている場合だけ商品名の部分一致条件を追加し、カテゴリが指定されている場合だけカテゴリの完全一致条件を追加しています。利用者がどちらか一方だけを入力しても検索でき、両方を指定した場合は二つの条件を使った検索になります。

動的検索とPredicateの考え方を理解する

Spring Bootの検索フォームでは、検索項目がすべて入力されるとは限りません。商品名だけ入力されることもあれば、カテゴリだけが選択されることもあります。このような場合に便利なのが、必要な検索条件だけをPredicateとして追加する動的検索です。

Predicateは検索条件を表します。キーワードが入力されていればlikeによるPredicateを追加し、カテゴリが指定されていればequalによるPredicateを追加します。この方法なら、検索項目が増えた場合でも条件を一つずつ追加できるため、処理を整理しやすくなります。

Spring Data JPAの検索機能を実装するときは、最初から複雑な動的検索に挑戦するよりも、まず一つのlike条件で検索できることを確認し、その後に二つ目の条件を追加すると理解しやすくなります。段階的に検索条件を増やすことで、CriteriaBuilder、CriteriaQuery、Root、Predicate、whereの役割も自然に理解できます。

大文字と小文字を区別しない検索も考える

英字を含む商品名や技術名、メールアドレス、英語タイトルなどを検索する場合は、大文字と小文字の扱いにも注意が必要です。データベースや設定によっては、大文字と小文字の違いが検索結果に影響する場合があります。

CriteriaBuilderにはlowerやupperがあり、検索対象の文字列を小文字または大文字にそろえて比較できます。検索キーワードも同じ形式にそろえることで、大文字と小文字を意識した検索条件を作成できます。

public List<Product> searchIgnoreCase(String keyword) {
    CriteriaBuilder cb = entityManager.getCriteriaBuilder();
    CriteriaQuery<Product> query = cb.createQuery(Product.class);
    Root<Product> root = query.from(Product.class);

    String pattern = "%" + keyword.toLowerCase() + "%";

    query.select(root);
    query.where(
        cb.like(cb.lower(root.get("name")), pattern)
    );

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

大文字と小文字をどのように扱うかは、利用しているデータベースや文字列比較の設定によっても異なります。そのため、実際のSpring Bootアプリケーションでは、開発環境で検索結果を確認しながら検索仕様を決めることが大切です。

ワイルドカードと入力値にも注意する

like検索では、ワイルドカードとして使われる文字に特別な意味があります。検索キーワードの前後にワイルドカードを追加することで部分一致検索を作れますが、利用者自身が入力した文字列にワイルドカードとして扱われる文字が含まれている場合には、想定していた検索結果と異なることがあります。

検索フォームから自由入力を受け取る場合には、入力された文字をそのまま検索パターンとして扱ってよいのかを考える必要があります。特殊な文字そのものを検索対象にしたい場合には、エスケープ処理についても理解しておくと、より実践的な検索機能を作成できます。

検索結果がゼロ件になる場合は、最初に単純な部分一致検索だけで動作を確認すると原因を見つけやすくなります。そこからカテゴリや販売状態など別の条件を一つずつ追加していけば、どの条件によって検索結果が変わっているのかを確認できます。

likeを理解すると実用的な検索画面へ発展できる

CriteriaBuilderのlikeは、Spring Bootのさまざまな検索機能へ応用できます。商品管理システムなら商品名の部分一致検索、会員管理システムなら氏名や住所の検索、記事管理システムならタイトルのキーワード検索などに利用できます。

さらに、likeで作成したPredicateをequalなど別の条件と組み合わせれば、商品名に指定したキーワードを含み、さらに特定のカテゴリに属している商品だけを検索するといった処理も作れます。検索フォームの項目が増えても、条件を一つずつPredicateとして整理することで対応しやすくなります。

CriteriaBuilderを学習するときは、likeだけを暗記するよりも、CriteriaBuilderは検索条件を作るもの、CriteriaQueryは問い合わせ全体、Rootは検索対象、Predicateは検索条件、whereは条件を問い合わせへ設定するものという役割を整理して覚えると理解しやすくなります。

Spring BootやSpring Data JPAによるデータベース検索では、完全一致検索だけでなく、利用者が入力したキーワードから候補を探す部分一致検索もよく利用されます。CriteriaBuilderのlikeを理解し、前方一致、後方一致、部分一致、equalとの使い分け、動的検索、大文字と小文字、ワイルドカードの注意点まで理解しておけば、より使いやすい検索画面を作成できるようになります。