SpringのCriteriaBuilderのdiffメソッドを完全解説！初心者でもわかるJPA Criteria APIの数値差分計算

1. CriteriaBuilderのdiffメソッドとは？

1. CriteriaBuilderのdiffメソッドとは？

Spring BootでJPAを使ったデータベース検索を実装するときは、JPQLだけでなくCriteria APIを使って検索条件をJavaコードで組み立てる方法があります。そのとき中心的な役割を持つのがCriteriaBuilderです。CriteriaBuilderは厳密にはSpring独自のクラスではなく、Jakarta Persistenceで定義されているインターフェースです。Spring BootやSpring Data JPAからJPAを利用する場面でも、この仕組みをそのまま使えます。

diffメソッドは、Criteria APIの検索式の中で数値の引き算を表現するためのメソッドです。英単語のdiffはdifferenceを連想すると理解しやすく、二つの数値の差を求めたいときに使います。例えば、商品テーブルに販売価格と仕入価格が保存されている場合、販売価格から仕入価格を引いて利益額を計算できます。ほかにも、現在庫数と基準在庫数の差、予定数量と実績数量の差、上限値と現在値の差など、データベースの数値列を使った差分計算に利用できます。

Criteria APIでは、単純にJavaのマイナス演算子を書くのではなく、検索式をExpressionとして組み立てます。そのため、差分を表す場合はCriteriaBuilderのdiffを使います。動的検索を作りたい場合や、複数の条件をJava側で安全に組み立てたい場合に覚えておくと便利なメソッドです。

2. diffメソッドの基本構文と三つの使い方

2. diffメソッドの基本構文と三つの使い方

CriteriaBuilderのdiffには、数値を表す式と式、式と固定値、固定値と式を組み合わせる形があります。どの形でも考え方は同じで、第一引数から第二引数を引いた結果を表すExpressionが返されます。つまり、引数の順番によって計算結果が変わる点が重要です。

一つ目は、データベースの列同士を引き算する使い方です。販売価格から仕入価格を引くような計算が代表例です。二つ目は、データベースの列から固定値を引く使い方です。販売価格から一律の値引額を引いた金額を求めるような場面で利用できます。三つ目は、固定値からデータベースの列を引く使い方です。目標値から現在値を引いて、あとどれだけ必要かを計算するような場合に使えます。

Spring Boot 3以降では、一般的にjakarta.persistence.criteria.CriteriaBuilderを利用します。古いSpring Boot 2系の記事ではjavax.persistence.criteria.CriteriaBuilderが出てくることがありますが、基本的なCriteria APIの考え方は同じです。初心者が検索するときは、Spring Boot CriteriaBuilder diff、JPA Criteria API 引き算、CriteriaBuilder 数値計算などのキーワードも参考になります。

3. 列同士を引き算して差額を取得する基本例

3. 列同士を引き算して差額を取得する基本例

最初に、商品を表すProductエンティティに販売価格のpriceと仕入価格のcostがあるとします。販売価格から仕入価格を引けば、商品ごとの利益額を計算できます。Criteria APIでは、それぞれの列をExpressionとして取得し、diffへ渡します。

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

Expression<Integer> price = root.get("price");
Expression<Integer> cost = root.get("cost");
Expression<Integer> profit = cb.diff(price, cost);

query.select(profit);

List<Integer> results = entityManager.createQuery(query).getResultList();

この例では、priceからcostを引いた計算式がprofitに入ります。ただし、ここで実際にJavaが全レコードを読み込んでから引き算しているわけではありません。Criteria APIがSQLに相当する検索式へ変換され、通常はデータベース側で計算が行われます。

例えば、販売価格が三千円で仕入価格が二千円なら差額は千円です。販売価格が五千円で仕入価格が三千五百円なら差額は千五百円です。このように、取得したい値そのものを差分計算にできるため、集計画面や管理画面で計算結果だけを取得したい場合にも使えます。

1000
1500

初心者が注意したいのは、root.getで指定する名前は、基本的にデータベースの物理カラム名ではなくエンティティのフィールド名や属性名として扱われることです。エンティティ側の名前と一致しているか確認しましょう。

4. 列から固定値を引いて計算する方法

4. 列から固定値を引いて計算する方法

diffは列同士だけでなく、数値の列から固定値を引くこともできます。例えば、すべての商品について販売価格から百円を引いた値を取得したい場合、第二引数に固定値を指定します。キャンペーンの値引後価格を計算したり、基準値との差を確認したりするときに便利です。

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

Expression<Integer> price = root.get("price");
Expression<Integer> discountedPrice = cb.diff(price, 100);

query.select(discountedPrice);

List<Integer> results = entityManager.createQuery(query).getResultList();

このコードでは、商品ごとの販売価格から百を引いた値が検索結果になります。販売価格が二千円なら千九百円、三千五百円なら三千四百円という考え方です。単純な例ですが、固定の手数料、固定の控除額、基準値との差を求める場合にも同じ書き方を応用できます。

ここで重要なのは、第一引数と第二引数の順番です。cb.diff(price, 100)は販売価格から百を引きますが、cb.diff(100, price)にすると百から販売価格を引く意味になります。引き算では順番を入れ替えると結果の符号まで変わるため、検索条件が思った結果にならないときは引数の順番を確認してください。

5. 固定値から列を引いて残りの数値を求める方法

5. 固定値から列を引いて残りの数値を求める方法

目標値や上限値から現在の値を引きたい場合は、固定値を第一引数にして、列を第二引数に指定します。例えば、倉庫に保管できる上限を千個とし、現在庫数をstockとして管理している場合、千から現在庫数を引けば残りの保管可能数を計算できます。

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

Expression<Integer> stock = root.get("stock");
Expression<Integer> remaining = cb.diff(1000, stock);

query.select(remaining);

List<Integer> results = entityManager.createQuery(query).getResultList();

現在庫数が六百なら残りは四百、現在庫数が八百五十なら残りは百五十です。この形は、予算から使用額を引く、目標数から達成数を引く、最大件数から現在件数を引くなどの処理に応用できます。

Criteria APIは条件をJavaコードとして表現できるため、入力内容や画面の検索条件に応じて式を追加したい場合にも向いています。Spring Data JPAで単純なメソッド名検索だけでは表現しにくい計算条件を扱うとき、EntityManagerとCriteriaBuilderを組み合わせる方法を知っておくと実装の幅が広がります。

6. diffの計算結果をWHERE条件に使う方法

6. diffの計算結果をWHERE条件に使う方法

diffで作成した差分の式は、取得する値として使うだけではありません。検索条件の中にも利用できます。例えば、販売価格から仕入価格を引いた利益額が三百円以上の商品だけを検索したい場合、差分を表すExpressionを作り、それをwhere条件へ渡します。

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

Expression<Integer> price = root.get("price");
Expression<Integer> cost = root.get("cost");
Expression<Integer> profit = cb.diff(price, cost);

query.select(root);
query.where(cb.ge(profit, 300));

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

cb.geは以上という条件を表すため、この例では利益額が三百以上の商品が対象になります。販売価格だけで検索するのではなく、二つの列を計算した結果を条件にできる点がdiffの便利なところです。

例えば、予定数と実績数の差が一定以上のデータだけを抽出したり、予算と支出の差が少なくなったデータだけを表示したりできます。業務システムでは、単一の列の値ではなく複数の値の関係を条件にしたい場面が多いため、CriteriaBuilderの数値演算を理解しておくと複雑な検索にも対応しやすくなります。

7. diffの計算結果で並び替える方法

7. diffの計算結果で並び替える方法

差分の結果は並び替えにも使えます。例えば、販売価格から仕入価格を引いた利益額が大きい商品から順番に表示したい場合は、diffで作成した式をdescへ渡します。反対に小さい順にしたい場合はascを使います。

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

Expression<Integer> price = root.get("price");
Expression<Integer> cost = root.get("cost");
Expression<Integer> profit = cb.diff(price, cost);

query.select(root);
query.orderBy(cb.desc(profit));

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

この検索では、単純に販売価格が高い順ではなく、販売価格と仕入価格の差が大きい順に商品を並べられます。管理画面で利益の大きい商品を上位に表示したい場合や、在庫の不足数が大きい順に確認したい場合などに応用できます。

Criteria APIでは、検索条件、取得項目、並び替えを同じ考え方で組み合わせられます。diffで作ったExpressionを一度変数にしておくと、条件指定と並び替えの両方で再利用でき、コードの意味も読み取りやすくなります。

8. IntegerやLongやBigDecimalを扱うときの考え方

8. IntegerやLongやBigDecimalを扱うときの考え方

diffは数値を扱うメソッドなので、エンティティの数値型に合わせて利用します。件数や在庫数ならIntegerやLong、金額なら設計によってBigDecimalを使うことがあります。どの型を使う場合でも、まずエンティティ側の型とCriteria APIで扱う式の型を揃えることが大切です。

特に初心者がつまずきやすいのは、同じ数値に見えてもJavaでは型が異なる点です。整数の列に対して小数を前提とした値を混ぜたり、Longの列に対して型を意識せず固定値を渡したりすると、型推論が分かりにくくなることがあります。エラーが出た場合は、対象フィールドのJava型を確認し、Expressionの型と固定値の型が自然に対応しているかを見直してください。

また、金額計算では小数の丸めや精度も重要です。diff自体は差を表す検索式を作るメソッドであり、業務上必要な丸め規則まで自動で決めてくれるものではありません。税額や割引率を組み合わせる場合は、データベースの数値型、Javaの型、JPAプロバイダが生成するSQLを含めて確認すると安全です。

9. diffメソッドを使うときに覚えておきたい注意点

9. diffメソッドを使うときに覚えておきたい注意点

まず、diffは数値の差を求めるためのメソッドであり、日付同士の経過日数をそのまま求める用途には使えません。日付の差を求めたい場合は、使用しているデータベースの関数やJPAプロバイダの対応方法を確認し、必要に応じてCriteriaBuilderのfunctionなどを検討します。日付計算はデータベース製品による違いが出やすいため、数値のdiffとは分けて考えると理解しやすくなります。

次に、引き算する列にnullが含まれる場合にも注意が必要です。一般的なSQLの計算では、どちらかがnullなら計算結果もnullになることがあります。必ず数値が入る設計なら問題になりにくいですが、未設定を許可している列では検索結果が想定と違わないか確認してください。必要ならデータベース設計で非null制約を付けるか、Criteria APIで既定値を扱う方法を検討します。

さらに、文字列で指定する属性名の打ち間違いにも気を付けます。root.get("price")のような書き方は分かりやすい一方、名前を間違えてもコンパイル時に気付きにくい場合があります。規模の大きいプロジェクトでは、JPAのメタモデルを利用して型安全性を高める方法もあります。初心者の段階では、まずエンティティのフィールド名を確認しながら正確に記述する習慣を付けるとよいでしょう。

Spring Data JPAでSpecificationを使っている場合も、内部ではCriteriaBuilderを利用できるため、diffを検索条件へ組み込めます。単純な一致検索だけでなく、価格差、利益額、在庫差、目標との差などを動的検索へ追加したいときに役立ちます。CriteriaBuilderのdiffメソッドは短いメソッドですが、取得値、絞り込み、並び替えへ応用できるため、Spring BootとJPAで実務的な検索処理を作るうえで覚えておきたい機能です。

まとめ

まとめ

Spring BootやSpring Data JPAでデータベース検索を作るとき、条件が単純な一致検索だけであれば、Repositoryのメソッド名から検索処理を組み立てる方法でも十分に対応できます。しかし、販売価格と仕入価格の差を求めたい場合や、在庫数と基準在庫数の差を検索条件にしたい場合など、複数の数値を計算しながら検索したい場面では、JPAのCriteria APIが役立ちます。その中で数値の引き算を表現するために使えるのが、CriteriaBuilderのdiffメソッドです。

CriteriaBuilderのdiffは数値の差を検索式として表現する

CriteriaBuilderは、Criteria APIで検索条件や計算式を組み立てるために利用するインターフェースです。Spring独自の機能ではなく、Jakarta Persistenceで定義されている仕組みですが、Spring BootでJPAを使う開発では頻繁に登場します。CriteriaBuilderを使うと、等しい、以上、以下、文字列検索、並び替え、数値計算などをJavaコードとして組み立てられます。

diffメソッドは、その中でも数値の差を求める役割を持っています。第一引数から第二引数を引くという単純な考え方なので、基本を理解すれば難しくありません。例えば、販売価格から仕入価格を引けば利益額を表せますし、目標在庫数から現在庫数を引けば不足している在庫数を表せます。単なる計算結果の取得だけでなく、その差を検索条件や並び替えに利用できるところが重要です。

列同士の引き算は利益や差額の計算に使える

実務で分かりやすい例が、商品テーブルの販売価格と仕入価格から利益額を求める処理です。エンティティにpriceとcostという数値属性がある場合、それぞれをExpressionとして取得し、diffに渡すことで、価格差を表す検索式を作れます。Java側で全件を取得してから一件ずつ引き算するのではなく、Criteria APIが生成する問い合わせの中で計算できるため、データベース検索の一部として扱えます。

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

Expression<Integer> price = root.get("price");
Expression<Integer> cost = root.get("cost");
Expression<Integer> profit = cb.diff(price, cost);

query.select(profit);

List<Integer> results = entityManager.createQuery(query).getResultList();

この書き方では、販売価格から仕入価格を引いた結果だけを取得できます。商品ごとの利益一覧を作りたい場合や、差額を画面に表示したい場合にも応用できます。CriteriaBuilderのdiffは、二つの列の関係をそのまま検索式として扱えるため、単独の列だけでは表せない条件を作るときに便利です。

列と固定値の差も簡単に表現できる

diffメソッドでは、列同士だけでなく、列と固定値を組み合わせた引き算もできます。例えば、商品の販売価格から一律の値引額を引いた価格を求めたい場合は、価格を表すExpressionと固定値をdiffへ渡します。反対に、目標値や上限値から現在値を引きたい場合は、固定値を第一引数にして列を第二引数にします。

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

Expression<Integer> stock = root.get("stock");
Expression<Integer> remaining = cb.diff(1000, stock);

query.select(remaining);

List<Integer> results = entityManager.createQuery(query).getResultList();

この例では、上限を千個として、そこから現在庫数を引いた残りの数量を求めています。同じ考え方で、予算から支出額を引く、目標件数から達成件数を引く、上限ポイントから使用ポイントを引くといった処理にも利用できます。Spring Bootの業務システムでは、基準値との差を求める処理が多いため、固定値とExpressionを組み合わせる方法も覚えておくと便利です。

diffの結果はWHERE条件にも利用できる

CriteriaBuilderのdiffは、計算結果を取得するだけのメソッドではありません。作成したExpressionを比較条件へ渡すことで、差額を使った絞り込みができます。例えば、販売価格から仕入価格を引いた利益額が一定以上の商品だけを検索したい場合は、diffで利益額を作り、geなどの比較メソッドと組み合わせます。

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

Expression<Integer> profit = cb.diff(
    root.get("price"),
    root.get("cost")
);

query.select(root);
query.where(cb.ge(profit, 500));

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

この検索では、価格そのものではなく、販売価格と仕入価格の差が五百以上の商品を抽出できます。予定数と実績数の差が大きいデータだけを探す、在庫不足が一定以上の商品だけを表示する、予算残高が基準以下になったデータを調べるなど、差分を使った検索条件はさまざまな業務処理に応用できます。

Spring Data JPAのSpecificationを使って動的検索を作る場合でも、引数として渡されるCriteriaBuilderを利用して同じようにdiffを組み込めます。画面から入力された条件に応じて価格差の条件を追加したり、複数のPredicateと組み合わせたりできるため、検索条件が多い管理画面でも活用できます。

差分を使った並び替えも実務で役立つ

diffで作った数値式は、orderByにも利用できます。利益額が大きい商品から順番に並べる場合はdesc、差額が小さい順に確認したい場合はascと組み合わせます。単純な販売価格順や商品名順ではなく、計算結果を基準に並べられるため、管理画面や集計画面で特に便利です。

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

Expression<Integer> profit = cb.diff(
    root.get("price"),
    root.get("cost")
);

query.select(root);
query.orderBy(cb.desc(profit));

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

このように、一度作成したExpressionは検索条件だけでなく並び替えにも利用できます。複雑なCriteria APIのコードでは、計算式を意味の分かる変数名へ入れておくと読みやすくなります。profitやremainingのように処理内容が伝わる名前を付けることで、後からコードを読む人にも意図が伝わりやすくなります。

数値型とnullの扱いを確認することも大切

CriteriaBuilderのdiffを使うときは、対象となるエンティティ属性の数値型にも注意が必要です。在庫数や件数ならIntegerやLong、金額ならBigDecimalなどが使われます。Expressionの型と固定値の型が不自然な組み合わせになっていると、型推論が分かりにくくなったり、期待していたSQLが生成されなかったりすることがあります。エラーになった場合は、まずエンティティの属性型を確認し、root.getで取得している型とdiffへ渡している値の型を見直します。

また、計算対象の列にnullが入る可能性がある場合も確認が必要です。一般的なSQLの数値計算では、片方がnullであれば計算結果もnullになることがあります。そのため、必ず値が必要な項目にはデータベース側で非null制約を設定する方法が考えられます。未設定を許可する設計であれば、どのような値として扱うのかをアプリケーションの仕様として決めておくことが重要です。

さらに、diffは数値の差を扱うためのメソッドなので、文字列や日付をそのまま引き算する用途には使いません。日付の差を求める処理では、データベース関数やJPAプロバイダが対応している関数を利用する必要があります。CriteriaBuilderにはfunctionを使ってデータベース関数を呼び出す方法もありますが、データベース製品ごとに動作が異なる場合があるため、数値のdiffとは分けて考えると理解しやすくなります。

CriteriaBuilderを理解すると動的検索の幅が広がる

CriteriaBuilderのdiffは一つの小さなメソッドですが、Criteria API全体を学ぶ入口としても役立ちます。Criteria APIでは、equalやlikeなどによる条件指定、andやorによる条件の組み合わせ、ascやdescによる並び替え、sumやprodなどを使った数値計算といったさまざまな処理をJavaコードから組み立てられます。diffを理解したあとに関連するCriteriaBuilderのメソッドも確認すると、Spring BootとJPAを使った検索処理をより柔軟に作れるようになります。

初心者のうちはCriteriaQueryやRoot、Expression、Predicateなどの名前が多く、Criteria APIを難しく感じることがあります。その場合は、まずEntityManagerからCriteriaBuilderを取得し、CriteriaQueryを作成し、Rootからエンティティ属性を取得し、最後にselectやwhereを指定するという基本の流れを整理すると理解しやすくなります。diffはその途中で数値の引き算を表すExpressionを作るものだと考えると、全体の位置付けが見えてきます。

Spring Bootで検索条件が増えてきたときや、Spring Data JPAのメソッド名だけでは表現しにくい計算条件が必要になったときは、CriteriaBuilderとCriteria APIが有力な選択肢になります。販売価格と仕入価格の差、現在庫と目標在庫の差、予算と支出の差などを条件として扱いたい場合は、diffメソッドを思い出すとよいでしょう。数値差分の取得、条件検索、並び替えという三つの使い方を押さえておけば、実際のデータベース検索でも応用しやすくなります。