GraphQL
クライアントが取得するフィールドを選ぶクエリ言語
どのようなものか
GraphQLは、API向けのクエリ言語と、そのクエリをサーバーで実行するランタイムを合わせたものです。クライアントは欲しいフィールドを正確に指定した文書を送り、サーバーは同じ形のデータを返します。仕様は、クライアントとサーバーからなるアプリケーションのための言語と実行エンジンと説明します。2012年に生まれ、2015年にオープン標準としての作業が始まり、2019年からはJoint Development Foundation傘下のGraphQL Specification Projectの成果物になったと記録しています。最新は2025年9月版です。
出発点は、サービスが公開するスキーマです。名前付きのフィールドを持つ型の集合で、各フィールドにも型があります。組み込みのスカラー型はInt、Float、String、Boolean、IDで、UUID用など、独自のスカラーも追加できます。!を付けなければ、すべての型はnullを許します。String!は決してnullになりません。リストは角括弧で書き、[LineItem!]!なら、必ず存在し、nullの要素を持たないリストです。スキーマ自体にも問い合わせられます。クライアントはイントロスペクションのフィールド__schemaと__typeで、サービスの提供するものを尋ねられ、開発ツールやクライアントライブラリーも、これを基に作っています。
操作は三種類あります。クエリは、仕様の言葉で「読み取り専用の取得」、ミューテーションは、書き込みに続く取得、サブスクリプションは、一連の出来事に応じて時間とともにデータを届ける、長く続くリクエストです。サーバーでは、各フィールドに、その値を作る、一般にリゾルバーと呼ぶ関数があります。サービスは、まずスキーマに照らして操作を検証し、その後で、選ばれたフィールドのリゾルバーだけを呼びます。ミューテーションの最上位フィールドは、並列ではなく順番に実行するため、同じリクエストの二つの書き込みが競合しません。
仕様は、転送方法もシリアライズ形式も定めません。最も一般的なのはHTTPで、GraphQL APIは普通、末尾が/graphqlの一つのURLで提供し、最も一般的な形式のJSONで答えます。クライアントは、JSON本文にqueryの文字列と、必要ならvariablesを入れてPOSTを送ります。サーバーはクエリならGETも受け付けられますが、ミューテーションは必ずPOSTです。結果はdata、問題があればerrorsへ入ります。この分野のGraphQL Foundationのガイドは、まだ草案のGraphQL-over-HTTP仕様に従います。

写真: HNBS / Pixabay 
写真: kareni / Pixabay
用語の背後にある前提を検証する
解説とリンク先の実績を参考に、プロジェクトについての質問を整理してください。ツールを選ぶ前に、前提を一緒に検討できます。 ETL/ELTパイプライン6本を設計・運用 — 6 3種類のDBエンジンにまたがるETLパイプライン
なぜ重要なのか
大半のHTTP APIでは、各エンドポイントが返すものをサーバーが決めます。注文の状態と顧客名が欲しい画面は、求めたより多い、注文全体と顧客全体を受け取るか、リソースごとにリクエストし、応答を自分でつなぐ必要があります。仕様は、この二つを過剰取得と取得不足と呼びます。GraphQLは関係を逆にします。クライアントはフィールド単位で求め、そのフィールドだけを受け取ります。注文から明細、顧客へと、一つのリクエストで関係もたどれます。リクエストが、受け取るデータと同じ形だからです。
型システムは、二つの面で役立ちます。リゾルバーを一つでも動かす前に、すべての操作をスキーマで検証するため、フィールド名の誤記や型の違う引数があれば、何も実行せず、操作全体を拒否します。ツールも、コードを書いているうちに同じ誤りを見つけられます。また、クライアントは選んだフィールドしか受け取らないため、フィールドを追加しても、既存のクライアントに負担をかけません。そのため、バージョン番号なしでAPIを発展させられます。古いものの隣に新しいフィールドを加え、古いものは理由付きの@deprecatedで印を付けます。既存のクライアントを壊さないよう、有効なまま保ち、使うクライアントがなくなってから消します。
こうした仕組みには実際に代償があり、その大半はHTTP本来の仕組みを外れることから生まれます。個々の対象をURLで識別せず、すべて一つのアドレスへ、普通はPOSTで送ります。一方、既定でキャッシュ可能と扱うのは、一般にGETです。REST APIが中継サーバーから自然に得るキャッシュを、意図して作り直す必要があります。データとエラーが一緒に返っても、HTTPでは成功になるため、状態コードだけでは全体を語れません。クライアントは、サーバーが見たことのないリクエストを構成します。一件で大量の仕事を求められるため、その負荷からサーバーを守るのはサービスの仕事で、GraphQLが代わりにするものではありません。フィールドごとのリゾルバーは簡単に書けますが、単純に実装すると、背後のデータベースへの問い合わせが多くなります。
実際の活用例
明細と顧客を持つ注文について、スキーマのごく一部を示します。
type Query {
order(id: ID!): Order
}
type Order {
id: ID!
status: String!
items: [LineItem!]!
customer: Customer
}
type LineItem {
name: String!
quantity: Int!
}
type Customer {
name: String!
}注文の状態、明細、顧客名を表示する画面は、この操作を/graphqlへPOSTの本文で送り、変数に{"id": "7421"}を渡します。
query OrderSummary($id: ID!) {
order(id: $id) {
status
items {
name
quantity
}
customer {
name
}
}
}注文と明細は解決できても、customerの背後のサービスが停止しているとします。応答は、作れたものをすべて含みます。失敗したフィールドはnullで、errorsの項目が、何が問題で、文書のどこで起き、応答のどの経路に影響するかを示します。8行目の5列目がcustomerです。
{
"data": {
"order": {
"status": "open",
"items": [{ "name": "notebook", "quantity": 2 }],
"customer": null
}
},
"errors": [
{
"message": "Customer service unavailable",
"locations": [{ "line": 8, "column": 5 }],
"path": ["order", "customer"]
}
]
}customerはnullを許す宣言なので、影響はそこで止まります。もしCustomer!なら、エラーは親へ伝わり、注文全体がnullで返ります。また、dataはnullではないため、エラーがあってもサーバーは2xxで答えます。HTTPには部分的な成功の状態コードがないためです。状態コードしか見ないクライアントは、これを完全な応答と扱います。
反対に、応答の形をすべてサーバーが決める設計を、このサイトの事例の一つで作りました。PostgresからAPIへJSONをそのまま通す実装では、PostgreSQLの関数が応答全体をJSONに組み立て、Goのハンドラーは変更せず転送します。そのため、関数の戻すものを変えれば、ハンドラーを一行も編集せずに、クライアントの受け取るものが変わります。そこではフロントエンドが、データベースの与える形へ直接依存します。GraphQLではクライアントがフィールドを指定し、サーバーは、スキーマが許す、どの組み合わせでも解決できる必要があります。
問題が起きるところ
一つのフィールドで、データベースを千回呼びます。 リゾルバーはフィールドごとの小さい関数で、単純な実装では、オブジェクトを一つずつ処理します。各注文の顧客も含む一覧なら、一覧用に一回、各注文にさらに一回のデータベース呼び出しが必要です。GraphQL FoundationのガイドはN+1問題と呼び、まとめて処理する方法を示します。短い時間枠に要求された読み込みを集め、FacebookのDataLoaderなどで、一つのリクエストとしてデータベースへ送ります。
一つのリクエストが、すべてを求めます。 操作を書くのはクライアントなので、一文書で友人の友人を何層も深くたどったり、重いフィールドを百個の別名で繰り返したり、多くの操作を一つのリクエストへ詰めたりできます。どれも有効なGraphQLで、どれもサーバーを占有しかねません。防御はサービス側で行います。リストのフィールドをページ分割し、実行前に深さや幅の上限を超える操作を拒否し、別名の数とバッチの大きさを制限します。さらに細かくするなら、各フィールドへ重みを与え、見積もった負荷が予算を超える操作を拒否します。クエリ複雑度解析と呼ぶ手法ですが、仕様自体は、その規則を定めません。自社のクライアントだけに提供するAPIなら、事前に保存してハッシュで探す操作だけを実行する、信頼済み文書の方式で、さらに制限できます。
200 OKが失敗を隠します。 上の例のように、エラーを含む応答も2xxになり得ます。古いメディア型application/jsonについて、ガイドはさらに、正しいリクエストを実行できなかった場合でも2xxを勧め、一部の古いサーバーは、検証エラーでも2xxを返します。クライアントと周囲の監視は、状態だけでなくerrorsを読む必要があります。新しいメディア型application/graphql-response+jsonなら、正しいリクエストが実行できない場合は4xxか5xxとなり、状態が再び意味を持ちます。クライアントはAcceptヘッダーで、この形式を求めるべきです。
キャッシュが機能しなくなります。 どの操作も同じURLへのPOSTなので、CDNを含む、クライアントとサーバーの間のキャッシュからは、一つのアドレスと、既定ではキャッシュしないメソッドに見えます。クエリをGETで送れば役立ちますが、長い文書はブラウザーやCDNが許すURL長を超える場合があります。永続化クエリは両方を解決します。クライアントはハッシュを送り、サーバーは文書全体を引き出してから、検証、実行します。HTTPで応答をキャッシュするなら、機微な情報を含む応答はプライベートキャッシュに限って保存するか、まったくキャッシュしない必要があります。
フィールドが消えます。 クライアントは一つずつ選ぶため、フィールドの削除や改名は、それを選ぶすべてのクライアントを壊します。軽い影響では済みません。存在しないフィールドを指定した操作は、全体が検証に失敗し、データは何も返りません。仕様が非推奨のフィールドも有効に保つのは、既存のクライアントを壊さないためです。まず代わりを追加し、新しいものを示す理由を付けて、古いものを@deprecatedにします。どのクライアントも選ばなくなってから、古いフィールドを削除します。
参考資料
- GraphQL仕様の各版 — 2015年7月から2025年9月版までの全版と、作業中の草案です。言語、型システム、検証、実行、エラーを扱います。
- HTTPでの提供 — 単一エンドポイント、POSTとGET、二つの応答メディア型、それぞれの状態コードの規則です。
- 性能 — クエリのGET送信、永続化クエリ、N+1問題、バッチ処理です。
- セキュリティ — 信頼済み文書、深さ、幅、バッチの制限、クエリ複雑度解析、および本番でのイントロスペクションとエラーの詳細です。

