GraphQL
エンジニアのためのWebチートシート

GraphQLはAPIのためのクエリ言語であり、既存のデータに対するクエリを実行するためのランタイムです。クエリ、ミューテーション、型システム、スキーマ定義、フラグメント、ページネーションなどをチートシートにまとめました。

基本クエリ

クエリの基本

フィールドを指定してデータを取得します。

# 省略形（queryキーワードを省略）
{
  user { id, name, email }
}

# 名前付きクエリ
query GetUser {
  user { id, name }
}

# ネストしたフィールド
query {
  user {
    name
    posts {
      title
      comments { text }
    }
  }
}

引数

フィールドに引数を渡して結果を絞り込みます。

# スカラー引数
{ user(id: "1") { name } }

# Enum引数
{ hero(episode: JEDI) { name } }

# 複数引数
{
  users(limit: 10, offset: 20) {
    name
    email
  }
}

エイリアス

同じフィールドを異なる引数で複数回取得できます。

{
  empireHero: hero(episode: EMPIRE) {
    name
  }
  jediHero: hero(episode: JEDI) {
    name
  }
}

# レスポンス:
# {
#   "empireHero": { "name": "Luke" },
#   "jediHero": { "name": "R2-D2" }
# }

変数とディレクティブ

変数

クエリに動的な値を渡します。

# 必須変数（!付き）
query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
  }
}

# オプション変数（デフォルト値付き）
query GetHero($episode: Episode = JEDI) {
  hero(episode: $episode) {
    name
  }
}

# 変数JSON（別途送信）
# { "id": "1000", "episode": "NEWHOPE" }

ディレクティブ

フィールドの取得を条件付きで制御します。

# @include - 条件付きでフィールドを含める
query Hero($withFriends: Boolean!) {
  hero {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

# @skip - 条件付きでフィールドを除外
query Hero($skipBio: Boolean!) {
  hero {
    name
    bio @skip(if: $skipBio)
  }
}

フラグメント

名前付きフラグメント

再利用可能なフィールドセットを定義します。

fragment UserFields on User {
  id
  name
  email
  avatar
}

query {
  currentUser {
    ...UserFields
  }
  adminUser {
    ...UserFields
    role
  }
}

インラインフラグメント

Union/Interface型で具体的な型のフィールドにアクセスします。

query Search($text: String!) {
  search(text: $text) {
    __typename
    ... on User {
      name
      email
    }
    ... on Post {
      title
      body
    }
    ... on Comment {
      text
      author { name }
    }
  }
}

ミューテーション

基本ミューテーション

データの作成・更新・削除を行います。

mutation {
  createUser(
    name: "Alice"
    email: "alice@example.com"
  ) {
    id
    name
  }
}

# 複数のミューテーション（順次実行される）
mutation {
  createUser(name: "Alice") { id }
  createPost(title: "Hello") { id }
}
# createUserが先に実行され、次にcreatePost

変数付きミューテーション

変数とInput型を使って安全にデータを変更します。

mutation CreateReview($ep: Episode!, $review: ReviewInput!) {
  createReview(episode: $ep, review: $review) {
    stars
    commentary
  }
}

// 変数:
{
  "ep": "JEDI",
  "review": { "stars": 5, "commentary": "Great!" }
}

サブスクリプション

基本サブスクリプション

WebSocketでリアルタイムにデータを受信します。

# クライアント側: サブスクリプション
subscription OnCommentAdded($postId: ID!) {
  commentAdded(postId: $postId) {
    id
    content
    author {
      name
    }
  }
}

# スキーマ定義
type Subscription {
  commentAdded(postId: ID!): Comment
  messageReceived(roomId: ID!): Message
}

型システム

スカラー型

組み込みスカラー型の一覧です。
Type Description
Int 符号付き32ビット整数
Float 符号付き倍精度浮動小数点数
String UTF-8文字列
Boolean true / false
ID ユニーク識別子（文字列としてシリアライズ）

Type	Description
`Int`	符号付き32ビット整数
`Float`	符号付き倍精度浮動小数点数
`String`	UTF-8文字列
`Boolean`	`true` / `false`
`ID`	ユニーク識別子（文字列としてシリアライズ）

カスタムスカラー

独自のスカラー型を定義できます。

scalar Date
scalar URL
scalar JSON

type User {
  id:       ID!
  name:     String!
  homepage: URL
  birthday: Date
  metadata: JSON
}

オブジェクト型

フィールドの集合を持つ型を定義します。

type User {
  id:       ID!
  name:     String!
  email:    String
  age:      Int
  isActive: Boolean!
  posts:    [Post!]!
}

型修飾子

Null許容/非Null/リストの組み合わせです。

記法	意味
`String`	Null許容の文字列
`String!`	必須（非Null）の文字列
`[String]`	Null許容のリスト（要素もNull許容）
`[String!]`	Null許容のリスト（要素は非Null）
`[String]!`	必須のリスト（要素はNull許容）
`[String!]!`	必須のリスト（要素も非Null）

列挙型（Enum）

有限の選択肢を定義します。

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

enum UserStatus {
  ACTIVE
  INACTIVE
  SUSPENDED
}

type User {
  status: UserStatus!
}

ユニオン型

複数の型のいずれかを返すことを示します。

union SearchResult = User | Post | Comment

type Query {
  search(text: String!): [SearchResult]
}

# クエリ時はインラインフラグメントで分岐
{
  search(text: "hello") {
    ... on User { name }
    ... on Post { title }
    ... on Comment { text }
  }
}

インターフェース

共通フィールドを持つ型の契約を定義します。

interface Node {
  id: ID!
}

interface Character implements Node {
  id: ID!
  name: String!
  appearsIn: [Episode]!
}

type Human implements Character & Node {
  id: ID!
  name: String!
  appearsIn: [Episode]!
  totalCredits: Int
}

type Droid implements Character & Node {
  id: ID!
  name: String!
  appearsIn: [Episode]!
  primaryFunction: String
}

入力型（Input）

ミューテーションの引数に使う複合型です。

input CreateUserInput {
  name: String!
  email: String!
  age: Int
  role: UserRole = USER
}

input RegisterInput {
  name: String!
  email: String!
  address: AddressInput
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  register(input: RegisterInput!): User!
}

スキーマ定義

ルート型

スキーマのエントリポイントを定義します。

# デフォルトのルート型名
type Query { ... }
type Mutation { ... }
type Subscription { ... }

# カスタムルート型名（明示的なschema宣言が必要）
schema {
  query:        MyQueryType
  mutation:     MyMutationType
  subscription: MySubscriptionType
}

スキーマ例

Query/Mutation/型を組み合わせた完全な例です。

type Query {
  me: User
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User
  deleteUser(id: ID!): Boolean!
}

type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
  createdAt: String!
}

type Post {
  id: ID!
  title: String!
  body: String!
  author: User!
}

ドキュメントコメント

スキーマに説明を追加します。

"""
ユーザーを表す型
User type representing a registered user
"""
type User {
  "ユニークなID"
  id: ID!

  "表示名"
  name: String!

  "メールアドレス（ログインに使用）"
  email: String!
}

# 通常のコメント（スキーマドキュメントには含まれない）

エラーハンドリング

エラーレスポンス

GraphQLのエラーレスポンス形式です。

{
  "data": {
    "user": null
  },
  "errors": [
    {
      "message": "User not found",
      "locations": [
        { "line": 2, "column": 3 }
      ],
      "path": ["user"],
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

部分的成功

dataとerrorsが共存するケースです。

{
  "data": {
    "user": { "name": "Alice" },
    "posts": null
  },
  "errors": [
    {
      "message": "Cannot fetch posts",
      "path": ["posts"],
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ]
}

ページネーション

Offset方式

limit/offsetでページ分割します。

type Query {
  users(
    limit: Int = 10
    offset: Int = 0
  ): [User!]!
}

# 使用例
query {
  users(limit: 20, offset: 40) {
    id
    name
  }
}

Cursor方式（Relay）

Relay仕様のConnection/Edgeパターンです。

type Query {
  users(first: Int, after: String): UserConnection!
}

type UserConnection {
  edges: [UserEdge]
  pageInfo: PageInfo!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# 使用例
query {
  users(first: 10, after: "cursor123") {
    edges {
      cursor
      node { id name }
    }
    pageInfo { hasNextPage, endCursor }
  }
}

イントロスペクション

スキーマ情報の取得

__schemaで型一覧やルート型を取得します。

# 全型の一覧を取得
{
  __schema {
    types {
      name
      kind
    }
  }
}

# ルート型名を取得
{
  __schema {
    queryType { name }
    mutationType { name }
    subscriptionType { name }
  }
}

型情報の取得

__typeで特定の型のフィールド情報を取得します。

# 特定の型を検査
{
  __type(name: "User") {
    name
    kind
    description
    fields {
      name
      type {
        name
        kind
        ofType {
          name
          kind
        }
      }
    }
  }
}

GraphQLエンジニアのためのWebチートシート

基本クエリ

クエリの基本

フィールドを指定してデータを取得します。

引数

フィールドに引数を渡して結果を絞り込みます。

エイリアス

同じフィールドを異なる引数で複数回取得できます。

変数とディレクティブ

変数

クエリに動的な値を渡します。

ディレクティブ

フィールドの取得を条件付きで制御します。

フラグメント

名前付きフラグメント

再利用可能なフィールドセットを定義します。

インラインフラグメント

Union/Interface型で具体的な型のフィールドにアクセスします。

ミューテーション

基本ミューテーション

データの作成・更新・削除を行います。

変数付きミューテーション

変数とInput型を使って安全にデータを変更します。

サブスクリプション

基本サブスクリプション

WebSocketでリアルタイムにデータを受信します。

型システム

スカラー型

組み込みスカラー型の一覧です。

カスタムスカラー

独自のスカラー型を定義できます。

オブジェクト型

フィールドの集合を持つ型を定義します。

型修飾子

Null許容/非Null/リストの組み合わせです。

列挙型（Enum）

有限の選択肢を定義します。

ユニオン型

複数の型のいずれかを返すことを示します。

インターフェース

共通フィールドを持つ型の契約を定義します。

入力型（Input）

ミューテーションの引数に使う複合型です。

スキーマ定義

ルート型

スキーマのエントリポイントを定義します。

スキーマ例

Query/Mutation/型を組み合わせた完全な例です。

ドキュメントコメント

スキーマに説明を追加します。

エラーハンドリング

エラーレスポンス

GraphQLのエラーレスポンス形式です。

部分的成功

dataとerrorsが共存するケースです。

ページネーション

Offset方式

limit/offsetでページ分割します。

Cursor方式（Relay）

Relay仕様のConnection/Edgeパターンです。

イントロスペクション

スキーマ情報の取得

__schemaで型一覧やルート型を取得します。

型情報の取得

__typeで特定の型のフィールド情報を取得します。

GraphQL
エンジニアのためのWebチートシート