まくろぐ

GraphQL の仕様メモ

更新:
作成:

GraphQL 関連用語

クエリ文字列 (query string)
query {...} という文字列全体のこと。
操作タイプ (operation type, root type)
query {...} などの query というキーワード部分のこと。操作の種類を表しており、query の他には mutationsubscription があります。
操作名 (operation name)
query HogeHoge {...} などの HogeHoge の部分のこと。特に query 操作の場合は query name、mutation 操作の場合は mutation name と呼ぶことがあります。操作名の指定は multi-operation documents じゃない限りオプショナルですが、ログ解析やデバッグをしやすくするために、名前を付けることが推奨されています。
クエリ変数 (query variables)
query User($name: String!) {...} などの $name の部分のこと。
クエリ引数 (query arguments)
book(id: "xyz") {...} など、フィールド参照時に指定する id: "xyz" の部分のこと。クエリに変数が渡されている場合は、ここで book(id: $bookId) のような感じで参照できます。
選択セット、セレクションセット (selection sets)
query HogeHoge {...} などの {...} の部分のこと。どのフィールドを取得したいかを選択するので、選択セットと呼びます。
フィールド (field)
GraphQL オブジェクトの各プロパティ部分のこと。例えば、book { id title } というクエリで Book オブジェクトを取得するときの id とか title の部分。大きく分けて 2 種類あり、Scalar types(末端ノードそれ自体が値)と、Object types(ネストされたフィールドから構成される)があります。
入力オブジェクト型 (input object type, input types)
引数専用のオブジェクト型のこと。文字列 (String) や数値 (Int) などのスカラー値と比べて、複雑なデータを渡せます。例えば、新規データの作成要求 (mutation) を行うときに、新規データの内容を表現するために使われます。定義方法自体は普通のオブジェクト型 (type) と同様ですが、入力型 (input) はそれ自身のデータを取得する用途には使えないところが異なります(つまり、クエリ内のフィールドとしては指定できないということです)。

5 つの組み込みスカラー型 (Scalar types)

組み込みのスカラー型

型名意味
Int符号付き 32 ビット整数
Float符号付き倍精度浮動小数点数
String文字列(UTF-8 エンコーディング)
Booleantruefalse
ID一意の識別子。データ形式としては String と同様だが、ID はリーダブル(意味のある単語)にはなっていないことを示唆します。

その他はオブジェクト型、あるいはユーザー定義のスカラー型です。

ユーザー定義の型

ユーザーが自由に定義できる型は、オブジェクト型、スカラー型 (scalar)、列挙型 (enums) の 3 種類です。

スキーマ内での独自型の定義
# オブジェクト型
type Character {
  name: String!
  appearsIn: [Episode]!
}

# スカラー型
scalar Date

# 列挙型
enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

フラグメント (Fragments)

フラグメント は複数のオペレーションから再利用可能なセレクションセットです。 例えば、

fragment basicUserInfo on User {
  name
  age
}

と定義すると、クエリのセレクションセットの User オブジェクトの中で...basicUserInfo のように参照できるようになります。

query {
  user(name: "maku") {
    ...basicUserInfo
  }
}

上記のクエリは、次のように記述するのと同様に振舞います。

query {
  user(name: "maku") {
    name
    age
  }
}
レスポンス
{
  "data": {
    "user" {
      "name": "maku",
      "age": 14
    }
  }
}

フラグメントが役に立つのは、そのセレクションセットを使いまわすときです。

query {
  maku: user(name: "maku") {
    ...basicUserInfo
  }
  chiko: user(name: "chiko") {
    ...basicUserInfo
  }
}

上記のように単一クエリの中で同種のデータ(ここでは user)を要求する場合は、エイリアス(ここでは makuchiko)を付けることで、レスポンス内のプロパティ名がコンフリクトしないようにします。

レスポンス
{
  "data": {
    "maku": {
      "name": "maku",
      "age": 14
    },
    "hemu": {
      "name": "chiko",
      "age": 5
    },
  }
}

イントロスぺクション

GraphQL サーバーに対して次のようなクエリを投げると、どんなフィールドを指定できるかを調べることができます。

__schema { ... }
__type(name: "User") { ... }

関連記事

まくろぐ
サイトマップまくへのメッセージ