JdbcTemplateのqueryとqueryForObjectを完全解説！初心者でもわかるデータ取得の基本
新人
「Spring Bootでデータベースから値を取得するときに、queryとかqueryForObjectって出てくるんですが、正直どちらを使えばいいのか分かりません」
先輩
「JdbcTemplateでは、取得したいデータが一件なのか複数件なのかで、使うメソッドが分かれているんだ」
新人
「名前は似ていますけど、役割が違うということですか？」
先輩
「そうだね。queryとqueryForObjectの違いを理解すると、JdbcTemplateでのデータ取得が一気に分かりやすくなるよ」
1. queryとqueryForObjectとは何か
JdbcTemplateには、データベースからデータを取得するためのメソッドとして、 queryとqueryForObjectが用意されています。 どちらもselect文を実行するためのものですが、 取得するデータの件数によって役割がはっきり分かれています。
queryは、複数件のデータを取得するためのメソッドです。 一方で、queryForObjectは、一件だけ取得することが前提のメソッドになります。 この違いを意識することが、JdbcTemplate queryの基本になります。
名前だけを見ると分かりにくく感じるかもしれませんが、 queryは「問い合わせて一覧を取得する」イメージ、 queryForObjectは「一つの結果を取得する」イメージを持つと理解しやすくなります。 queryForObject 使い方 初心者の方は、まずこの考え方を覚えておきましょう。
2. なぜ二つのメソッドが用意されているのか
JdbcTemplateにqueryとqueryForObjectの二つが用意されている理由は、 データ取得の意図を明確にするためです。 一件取得したいのか、複数件取得したいのかを、 メソッド名の時点で表現できるようになっています。
例えば、IDを指定してユーザー情報を取得する場合は、 結果が一件であることが分かっています。 このようなケースでは、queryForObjectを使うことで、 「一件取得する処理である」という意図がコードから伝わります。
一方で、ユーザー一覧を取得するような処理では、 結果が複数件になる可能性があります。 この場合はqueryを使うことで、 「複数件のデータを扱う処理である」ことが自然に表現できます。 JdbcTemplate queryを使い分ける理由は、とてもシンプルです。
3. JdbcTemplateでデータを取得する全体の流れ
JdbcTemplateを使ったデータ取得の流れは、とても分かりやすい構造になっています。 まずはSQLを用意し、そのSQLをJdbcTemplateのメソッドに渡します。 その際に、queryかqueryForObjectのどちらを使うかを選びます。
Spring Boot環境では、依存関係とデータベース設定が正しく行われていれば、 JdbcTemplateは自動的に利用できる状態になっています。 ControllerからJdbcTemplateを注入して、そのままデータ取得処理を書けるのが特徴です。
@Autowired
private JdbcTemplate jdbcTemplate;
このようにJdbcTemplateを利用できる状態であれば、 あとはSQLとメソッドを正しく組み合わせるだけです。 データ取得処理の基本形を見てみましょう。
String sql = "select name from users where id = ?";
String name = jdbcTemplate.queryForObject(sql, String.class, 1);
この例では、一件だけデータを取得するためにqueryForObjectを使っています。 SQLの結果が一件であることが前提なので、 戻り値も単一の値になります。
String sql = "select name from users";
List<String> list = jdbcTemplate.queryForList(sql, String.class);
こちらは複数件のデータを取得する例です。 結果が複数になるため、Listとして受け取っています。 queryを使う場合は、 「複数件になる可能性がある」 という点を常に意識しておくことが大切です。
JdbcTemplate queryとqueryForObjectは、 難しい仕組みではありません。 SQLの結果が一件か複数件かを意識するだけで、 正しく使い分けられるようになります。 次のステップでは、 それぞれのメソッドの詳しい使い方を、さらに掘り下げて見ていきましょう。
4. queryForObjectの基本的な使い方（1件取得の考え方）
queryForObjectは、SQLの実行結果が必ず一件になると分かっている場合に使うメソッドです。 主に、主キーで検索する場合や、件数が一に限定される条件で使われます。 JdbcTemplate queryForObjectの最大の特徴は、 「一件だけ取得する」という前提が強く意識されている点です。
SQLとJdbcTemplateメソッドの対応関係で考えると、 select文の結果が一行一列、または一行分のデータになるケースが対象です。 そのため、戻り値も単一の値やオブジェクトになります。 ここで「一件なのか」を必ず意識することが重要です。
String sql = "select name from users where id = ?";
String name = jdbcTemplate.queryForObject(sql, String.class, 1);
この例では、IDを指定して一人のユーザー名を取得しています。 SQLの結果が一件であるため、queryForObjectを使うのが適切です。 JdbcTemplate queryForObjectは、 「結果が一件であることを前提にした取得方法」 だと覚えておくと分かりやすくなります。
5. queryの基本的な使い方（複数件取得の考え方）
queryは、SQLの実行結果が複数件になる可能性がある場合に使うメソッドです。 一覧画面の表示や、条件に一致するデータをまとめて取得する処理でよく使われます。 JdbcTemplate query 使い方の基本は、 「結果が何件になるか分からない」 という前提で考えることです。
queryを使う場合、戻り値はListになります。 一件も取得できない場合も、例外ではなく空のListが返ってくる点が特徴です。 そのため、件数チェックがしやすいというメリットがあります。
String sql = "select name from users";
List<String> names = jdbcTemplate.queryForList(sql, String.class);
この例では、usersテーブルに存在するすべての名前を取得しています。 結果が複数件になるため、queryを使ってListとして受け取っています。 JdbcTemplate queryは、 「複数件を前提としたデータ取得」 に向いているメソッドです。
6. 戻り値の違いと型の考え方
queryForObjectとqueryの大きな違いの一つが、戻り値の型です。 queryForObjectでは単一の値やオブジェクトが返り、 queryではListとして複数の値やオブジェクトが返ります。 この違いを理解しておくと、コードの読み書きが楽になります。
queryForObjectは、 StringやIntegerなどの単純な型を直接受け取ることもできます。 一方でqueryでは、 List<String>やList<Map>のように、 複数件をまとめて扱う形になります。
初心者の方は、 「戻り値が単体か、リストか」 という点だけを意識しておけば十分です。 JdbcTemplate queryForObjectとqueryの違いは、 戻り値の型を見るだけでも判断できるようになります。
7. 初心者が混乱しやすいポイント（件数・例外・null）
JdbcTemplate queryForObjectを使うときに、 初心者が特に混乱しやすいのがエラーや例外の挙動です。 queryForObjectは、 結果が一件であることを前提としているため、 件数が合わない場合に例外が発生します。
例えば、結果がゼロ件の場合や、 複数件返ってきた場合には、 実行時にエラーになります。 そのため、 「本当に一件になるかどうか」 をSQLの段階で考えることが大切です。
一方でqueryは、 結果がゼロ件でも空のListが返ってきます。 nullになることは基本的にありません。 この違いを知っておくことで、 「なぜエラーになるのか」 という疑問が減っていきます。
queryとqueryForObjectは決して怖いメソッドではありません。 SQLの結果件数が一件なのか複数件なのかを意識するだけで、 正しく使い分けられるようになります。 次は、Controllerからこれらのメソッドを どのように呼び出して使うのかを見ていきましょう。
8. @Controllerからquery / queryForObjectを呼び出す流れ
JdbcTemplateのqueryやqueryForObjectは、 Webアプリケーションでは@Controllerから呼び出されることが多いです。 ここで大切なのは、 「Controllerは画面とのやり取りを担当する」 という役割を意識することです。 今は完全に理解できなくても大丈夫なので、 処理の流れをざっくり掴むことを目標にしましょう。
Controllerでは、 リクエストを受け取り、 必要なデータをJdbcTemplateで取得し、 その結果を画面に渡します。 データ取得の細かい仕組みをすべて理解していなくても、 queryやqueryForObjectを呼び出すだけで、 データベースから値を取得できるのがSpring JDBCの良いところです。
@Controller
public class UserController {
@Autowired
private JdbcTemplate jdbcTemplate;
}
このようにJdbcTemplateをControllerに注入しておけば、 メソッドの中でqueryやqueryForObjectを使えます。 Controllerは、 「どのSQLを実行するか」 「結果をどの画面に渡すか」 を決める役割だと考えると分かりやすくなります。
@GetMapping("/user")
public String showUser(Model model) {
String sql = "select name from users where id = ?";
String name = jdbcTemplate.queryForObject(sql, String.class, 1);
model.addAttribute("name", name);
return "user";
}
この例では、 Controllerがデータ取得の入口になっています。 SQLの結果が一件であるためqueryForObjectを使い、 取得した値を画面に渡しています。 Controllerから直接JdbcTemplateを使っても問題ありません。
9. データ取得処理を書くときの設計の考え方
JdbcTemplate query 設計を考えるときに大切なのは、 Controllerとデータ取得処理の役割を分けて考えることです。 Controllerは、 リクエストの受付とレスポンスの制御を担当します。 一方で、 SQLやデータ取得の考え方は、 できるだけシンプルに保つことが重要です。
初心者のうちは、 Controllerの中にJdbcTemplateの処理を書いても問題ありません。 無理に設計を難しくする必要はなく、 「どこでqueryを使っているか」 が分かる状態を作ることが大切です。 Spring JDBC データ取得 基本としては、 まず正しく動くことを優先しましょう。
将来的には、 データ取得処理を別のクラスに切り出すこともありますが、 今はそのイメージを持つだけで十分です。 Controllerは画面寄りの処理、 JdbcTemplateはデータ取得担当、 という役割分担を頭の中で意識しておきましょう。
JPAを使う場合と比べると、 JdbcTemplateはSQLを直接書くスタイルです。 その分、 「どんなSQLが実行されているか」 が見えやすいという特徴があります。 考え方の違いとして、 JdbcTemplateはSQL中心、 JPAはオブジェクト中心、 という程度の理解で問題ありません。
10. query / queryForObjectを理解したあとの次のステップ
queryとqueryForObjectの基本が分かれば、 JdbcTemplateを使ったデータ取得の土台はできています。 今の段階で、 すべてを完璧に理解できていなくても大丈夫です。 「一件か複数件かで使い分ける」 という考え方が身についていれば十分です。
次のステップとしては、 取得したデータを自分で定義したクラスに変換する方法を学ぶと、 より実践的なコードが書けるようになります。 ただし、 いきなり難しい実装に進む必要はありません。 まずは、 queryやqueryForObjectを正しく使えることが最優先です。
JdbcTemplate query 設計を意識しながらコードを書くことで、 データ取得処理に対する苦手意識は少しずつ減っていきます。 今回学んだ内容をベースに、 次はRowMapperや、 独自クラスへの変換といったテーマに進んでいくと、 Spring JDBCの理解がさらに深まっていくでしょう。
