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 AddressInput {
  street: String!
  city:   String!
  zip:    String!
}

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
        }
      }
    }
  }
}

引用・参考リンク

Related Cheatsheets

Related Goods

GraphQLの基礎から実践まで、Webサービスを構築しながら学べる入門書。 REST APIとの違いも理解できる一冊です。
詳細をみる
GraphQL特集を収録したWeb技術専門誌。実践的なGraphQL活用事例が学べます。
詳細をみる
ケーブルに取り付け可能なTypeCとLightningの変換アダプタです。スタイリッシュなデザインで、Apple製品との相性抜群です。
詳細をみる
お気に入りのサウンドデバイスをすぐ取り出せる位置にディスプレイさせておくことができます。
詳細をみる

WebTerm - Recommended tools

WebTermは、ブラウザでLinuxコマンド・Gitコマンドを安全に実行でき、チュートリアル式で学べるターミナルサンドボックスです。
AIコーディングツールの普及に伴い、CLIの基礎知識を身につける重要性は増しています。実際のターミナルを操作するのに抵抗がある方でも、WebTermはローカル環境を壊す心配がありません。「会員登録不要・無料」で利用でき、学習環境として最適です。

WebTerm

Browser Terminal Sandbox for Learning CLI

開く

All Cheatsheets

エンジニア・プログラマー向けの便利なチートシートを多数まとめています(SP/Tablet/PC対応)

すべてのチートシートを見る

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