GraphQL Subscription

GraphQL Subscription とは

GraphQL Subscription は、GraphQL の 3 つの操作タイプ (Query, Mutation, Subscription) の 1 つで、サーバーからクライアントへリアルタイムにデータ更新を配信する仕組みである。仕様上は「ソースイベントに応じてデータを取得する長命なリクエスト」と位置づけられ、チャット、通知、ダッシュボードのリアルタイム更新に使われる。

押さえておきたいのは、GraphQL の仕様が Subscription の伝送方式を定めていないことだ。仕様が規定するのはストリームの生成・各ペイロードの内容・ストリームの終了までで、シリアライズ形式と伝送方式、そしてメッセージの到達確認・バッファリング・再送といった品質保証は実装側の選択に委ねられている。WebSocket が事実上の標準になっているのは仕様の要求ではなく実装の慣習であり、HTTP の Server-Sent Events を使う実装も存在する。到達保証が仕様に無いことは実務で効いてくる。接続が切れている間に発生したイベントは基本的に失われるため、再接続時に Query で現在の状態を取り直す経路を最初から用意しておく。

基本的な使い方

基本的な使い方の例を示す。

# スキーマ定義
type Subscription {
  orderStatusChanged(orderId: ID!): Order!
  newMessage(channelId: ID!): Message!
}

# クライアントからのサブスクリプション
subscription OnOrderStatusChanged($orderId: ID!) {
  orderStatusChanged(orderId: $orderId) {
    id
    status
    updatedAt
  }
}

Query / Mutation との違い

Query / Mutation との違いを以下にまとめる。

操作	方向	代表的な伝送方式	用途
Query	クライアント → サーバー	HTTP の 1 往復	データの取得
Mutation	クライアント → サーバー	HTTP の 1 往復	データの変更
Subscription	クライアントが購読を開始し、以後はサーバー → クライアント	WebSocket が主流 (仕様は伝送方式を規定しない)	イベント起点の更新

AWS AppSync での実装

AppSync は GraphQL Subscription をマネージドでサポートする。WebSocket の接続管理が不要で、Mutation をトリガーに自動的にサブスクライバーに配信する。

# AppSync: Mutation が実行されると、自動的に Subscription に配信
type Mutation {
  updateOrderStatus(orderId: ID!, status: String!): Order!
}

type Subscription {
  onUpdateOrderStatus(orderId: ID!): Order
    @aws_subscribe(mutations: ["updateOrderStatus"])
}

クライアントが onUpdateOrderStatus をサブスクライブしている状態で、別のクライアントが updateOrderStatus Mutation を実行すると、サブスクライバーに自動的に更新が配信される。

接続先には注意が必要だ。AppSync の購読は Query / Mutation を送る GraphQL エンドポイント (appsync-api.<リージョン>.amazonaws.com) ではなく、リアルタイム用の別ホスト (appsync-realtime-api.<リージョン>.amazonaws.com) への WebSocket 接続で確立される。社内プロキシの許可リストやブラウザーの CSP connect-src を設定するときは、この 2 つのホストを両方通しておく。

SSE / WebSocket API との使い分け

SSE / WebSocket API との使い分けを以下に整理する。

手法	用途	GraphQL 統合
GraphQL Subscription	GraphQL API のリアルタイム拡張	ネイティブ
WebSocket API (API Gateway)	カスタムプロトコル、チャット	手動実装
SSE	一方向のプッシュ通知	手動実装

GraphQL を既に使っているプロジェクトでは、Subscription が最も自然な選択だ。

スケーリングの課題

Subscription は永続接続を維持するため、接続数に応じてサーバーリソースが必要になる。自前で運用する場合、最初の壁は接続を保持するプロセスを水平に増やしたときだ。イベントを受け取ったノードと購読者がつながっているノードは一致しないので、全ノードへイベントを配る仕組み (Redis の Pub/Sub など) を別に用意することになる。

AppSync なら接続管理そのものは任せられるが、上限が消えるわけではない。2026 年 8 月時点の既定クォータでは、1 つのクライアント接続で保持できる購読文は 200 件、購読で受け取るメッセージのサイズは 240 KB、購読の無効化リクエストは 1 秒あたり 100 件である。このうちメッセージサイズは引き上げ申請の対象外なので、大きなオブジェクトをそのまま流す設計は行き詰まる。変更された ID と最小限のフィールドだけを配信し、本体はクライアントが Query で取り直す形にしておくと上限に当たりにくい。

GraphQL Subscription の関連書籍も参考になる。