GraphQLリゾルバーの仕組み — 欲しい項目が値になるまで

ひよこ

「名前だけください」って、誰が名前を探すの？

ペンギン先生

GraphQLの各フィールドの値を返す役目がリゾルバーだよ。ひよこのIDからユーザーを探し、そのユーザーから名前を取り出す、という具合に必要な項目をたどるんだ。

ひよこ

DBがなくても試せる？

ペンギン先生

うん。本文ではメモリ内のひよこの情報を使うよ。user(id: "1")でユーザーを返し、nameの値を読む流れを実行してみよう。DBを使う場合も、入口の考え方は同じだよ。

ひよこ

name用の関数も書くの？

ペンギン先生

ライブラリによっては、返したオブジェクトの同名プロパティを読む既定のリゾルバーがあるよ。nameがすでに入っていれば、その仕組みを使える。加工や追加の取得が必要なら関数を用意するんだ。

ひよこ

親と子ってどうつながるの？

ペンギン先生

userが返した値が、その中のnameやpostsなどを解決するための親の値になるよ。Queryの同じ階層は並行に実行できるけれど、子は必要な親の値が得られてから進むんだ。

ひよこ

更新する順番も自由なの？

ペンギン先生

Mutationの最上位のフィールドは、操作に書かれた順で直列に実行するよ。スキーマ定義の並び順ではないし、子のフィールドすべてが直列になるわけでもない。DBのトランザクションも別に設計するよ。

ひよこ

一つの項目でエラーになったら？

ペンギン先生

実行中のエラーはerrorsへ記録され、該当する値はnullとして扱うよ。ただしNon-Null（!）の項目なら親へ伝わり、data全体がnullになる場合もある。構文や検証で失敗した場合は実行前に止まるんだ。

ひよこ

一覧の人数だけDBへ問い合わせるの？

ペンギン先生

素朴な実装では、一覧1回と各ユーザーの関連データN回でN+1になることがある。DataLoaderでまとめる方法もあるけれど、DBへまとめて問い合わせるバッチ関数は自分で用意する必要があるよ。

ひよこ

認証情報はどう渡すの？

ペンギン先生

多くの実装にはcontextという共有値があるよ。利用者の権限やDBアクセスを渡し、見せてよい値だけを返す。DataLoaderのキャッシュも通常はリクエストごとに作り、別の利用者と混ぜないようにするんだ。

まず、ひよこの名前を取り出す

GraphQL入門と同じく、Node.jsと新しい作業フォルダーを使います。次の準備をしてから、コードを resolver-demo.mjs に保存してください。

npm init -y
npm install graphql

import { buildSchema, graphql } from 'graphql';

const schema = buildSchema(`
  type User { name: String! }
  type Query { user(id: ID!): User }
`);
const users = { '1': { name: 'ひよこ' } };
const rootValue = {
  user({ id }) {
    console.log('探したID:', id);
    return users[id] ?? null;
  },
};
const result = await graphql({
  schema,
  source: '{ user(id: "1") { name } }',
  rootValue,
});
console.log(JSON.stringify(result));

node resolver-demo.mjs で次の結果になります。

探したID: 1
{"data":{"user":{"name":"ひよこ"}}}

user が返したオブジェクトの name をGraphQL.jsの既定の処理が読みます。IDを "2" にすれば、この例では見つからず user が null になります。ここではHTTPサーバーやDBを使わず、解決処理だけを試しています。

親の値から、必要な項目をたどる

リゾルバーは一般に親の値、引数、context、実行情報を受け取ります。本文の buildSchema とルートオブジェクトを使う方法では、ルートのメソッドは引数オブジェクトを受け取ります。すべての書き方で同じ関数の引数順になるわけではありません。

user → posts → title なら、親が投稿の一覧を返した後、各投稿のタイトルを解決します。「必要な項目だけ返る」ことと、「裏側の取得も最小回数になる」ことは別です。DBや外部APIへの呼び出し回数を確認しましょう。

エラーと更新の順序

通常のフィールドは結果が順番に依存しないように設計します。Mutationの最上位は操作の記載順で直列ですが、複数の変更が一つのトランザクションになる保証はありません。

nullableなフィールドのエラーなら正常な部分のデータを返せる場合があります。Non-Nullの失敗は、nullを許す親まで伝わります。画面ではHTTPステータスだけでなく data と errors を確認してください。RESTでも部分的な結果を返す設計は可能で、単純な「全部成功か全部失敗か」の違いではありません。

もう少し詳しく：N+1とDataLoader

DataLoaderのJavaScript実装は、同じ実行のまとまりで要求されたキーをバッチ関数へ渡します。その関数がキーごとにDBを呼んでいたら、DBの問い合わせは減りません。結果はキーと同じ長さ・順番で返す必要があります。

通常はcontext内にリクエスト専用のDataLoaderを作ります。別の利用者でインスタンスを使い回すと、権限の違うデータをキャッシュから返すおそれがあります。JOINや一括取得も候補にし、実際の問い合わせ数を測りましょう。

ペンギン先生のまとめ

「リゾルバー」って出てきたら「指定された項目の値を用意する担当」と思えばだいたいOK！ 次はGraphQLとRESTの比較で、API全体の設計も比べてみましょう。

参考資料

• GraphQL：Execution — フィールド・親の値・実行
• GraphQL仕様：September 2025 — Mutationの最上位の直列実行とNon-Nullのエラー伝播
• GraphQL.js：Constructing Types — buildSchemaとルートの値
• DataLoader README — バッチ関数とリクエスト単位のキャッシュ