GraphQLの構成要素

GraphQLでそれぞれの要素が何と呼ばれて、どのように扱われているのかをまとめる。ほとんどは一般的な情報だと思うが、ライブラリについて言及する場合は以下の2つを用いることにする。

クライアント側の要素

query OperationName($variable: Type!) {
  selectionFields(argument: $variable) {
    id
    databaseId
    latestIssue {}
  }
}

クエリ(Query)

クライアントからサーバへ送られる query で記述された一連の文字列。例えば以下のようなものを意味する。

クエリドキュメント(Query Document)

複数のクエリを保存したファイルのこと。これはGraphQLというより gqlparser/v2 が便宜上用意した独自な概念のように思う。

オペレーション名(Operation Name)

query や mutation に続く名前のこと。これはクライアントが任意の名前を設定できる。

query OperationName() {}

変数(Variable)

オペレーション名に付属する引数部分のこと。

OperationName($variable: Type)

セレクション(Selection)

必要なフィールドを指示するための部分。ネストした部分もすべてセレクションとして扱う。

{
  user {
    name
  }
  path
}

フィールド(Field)

セレクションで選択されたひとつのフィールドを意味する。子孫フィールドを持つ場合、ひとつのフィールドに子孫のセレクションも内包する。従って以下すべてをひとつのフィールドと扱う。

user {
  id
  name
}

引数(Argument)

フィールドが持つ引数部分のこと。引数を持たないフィールドもある。

user(argument: $variable)

フラグメント(Fragment)

セレクションの共通部分を切り出してクエリで扱うための機能。フラグメントの定義部分(FragmentDefinition)と参照する部分(FragmentSpread)で構成される。定義部分は次のように on で型条件(Type Condition)を書く。こうすると UserProfile がインターフェイスであっても具体型が持つフィールドを参照できる。

fragment UserProfile on User {
  id
  name
}

当然だけど User はスキーマで定義しておく必要がある。参照する側はスプレッド演算子でセレクションに展開する。

user {
  ...UserProfile
}

gqlparser/v2 では FragmentSpread で参照できる。フラグメントの定義は FragmentDefinition で表現されている。

var a ast.SelectionSet
for _, s := range a {
  switch v := s.(type) {
  case *ast.FragmentSpread:
    cond := v.Definition.TypeCondition
    sel := v.Definition.SelectionSet
  }
}

インラインフラグメント(Inline Fragment)

フラグメントだけどスプレッドと同時に定義まで行うタイプの書き方。

{ ... on User { id name } }

この場合は InlineFragment として出現する。FragmentSpread と似ているが Definition がなくなっている。

var a ast.SelectionSet
for _, s := range a {
  switch v := s.(type) {
  case *ast.InlineFragment:
    cond := v.TypeCondition
    sel := v.SelectionSet
  }
}

サーバー側の要素

スキーマ(Schema)

GraphQLスキーマのこと。

型(Type)

GraphQLではいくつかある。

スカラー型
オブジェクト型
列挙型
ユニオン型
インターフェイス型
入力型

型モディファイア

以下の2種類は型モディファイアとして扱われる。

Non-Null
List

gqlparser/v2 では、例えば以下の型があった場合、

[String]!

これは次のような扱いとなる。

&ast.Type{
  NonNull: true,
  Elem: &ast.Type{
    NamedType: "String",
  },
}

スカラー型(Scalar)

単一の値だけで表現される型のこと。

scalar DateTime

独自に定義したものと、以下の基本型(Basic Types)を扱う。

String
Int
Float
Boolean
ID

gqlparser/v2 では ast.Definition 型の Kind と Name フィールドで表現する。

&ast.Definition{
  Kind: ast.Scalar,
  Name: "DateTime",
}

オブジェクト型(Object)

type で定義するオブジェクト型。

type PageInfo {
  pageNumber: Int!
  totalCount: Int!
}

gqlparser/v2 では ast.Definition 型の Fields フィールドで扱う。

&ast.Definition{
  Kind: ast.Object,
  Name: "PageInfo",
  Fields: []*ast.FieldDefinition{...},
}

列挙型(Enum)

これはそのまま列挙のこと。

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

gqlparser/v2 では ast.Definition 型の EnumValues フィールドで扱う。

&ast.Definition{
  Kind: ast.Enum,
  Name: "Episode",
  EnumValues: []*ast.EnumValueDefinition{
    {Name: "NEWHOPE"},
  },
}

ユニオン型(Union)

和結合した型を意味する。

union SearchResult = Human | Droid | Starship

gqlparser/v2 では ast.Definition 型の Types フィールドで扱う。

&ast.Definition{
  Kind: ast.Union,
  Name: "SearchResult",
  Types: []string{"Human", "Droid", "Starship"},
}

ディレクティブ(Directive)

他の言語では属性やアノテーションと言われているもの。

@directive(argument: Type) on WHERE | ELSEWHERE

WHERE には以下のようなものがある。

OBJECT
FIELD_DEFINITION
INTERFACE
SCHEMA
UNION
ARGUMENT_DEFINITION
SCALAR
ENUM
ENUM_VALUE
INPUT_OBJECT
INPUT_FIELD_DEFINITION