5 つの組み込みスカラー型 (Scalar types)
GraphQL 仕様で定義されているスカラー型は次の 5 つで、これらを各オブジェクト型のフィールドの型や、フィールド引数の型として使用します。
| 型名 | 意味 |
|---|---|
Int | 符号付き 32 ビット整数 |
Float | 符号付き倍精度浮動小数点数 |
String | 文字列（UTF-8 エンコーディング） |
Boolean | true または false |
ID | 一意の識別子。データ形式としては String と同様ですが、ID はリーダブル（意味のある単語）にはなっていないことを示唆します。ID は GraphQL サーバーとクライアントの間でオブジェクトの同一性を示すために使用します。 |
これ以外の型を使用したいときは、独自のオブジェクト型、スカラー型、列挙型を定義して使用します。
カスタムスカラー型 (Custom scalar types)
スカラー型にフォーマット制約を設けたいときや、任意のクラスのインスタンスとして扱いたいときは、独自の カスタムスカラー型 を定義します。
例えば、日時や E メールアドレス、UUID、URI などは、カスタムスカラーを使うべき典型的なフィールドの例です。
カスタムスカラーは、スキーマドキュメント内で scalar キーワードを使って定義できます。
"""
日時を表すスカラー型 (ISO 8601 形式の文字列)
"""
scalar DateTime
type Event {
title: String!
startAt: DateTime
}ライブラリの実装によりますが、カスタムスカラー型をそのまま使おうとすると、単なる String 型として扱われます。
カスタムスカラー型のデータを GraphQL サーバー型でどのようにハンドルするかは、サーバーライブラリごとに実装方法が提供されています。
例えば、下記は Golang の gqlgen ライブラリにおけるカスタムスカラー型のドキュメントです。
実装例として、yes や no として送られてきた文字列データを、Golang の bool 型として参照できるようにする方法が紹介されています。
カスタムスカラー型のデータは、サーバーには文字列として送られてきますが、サーバー側でカスタムスカラー用の Unmarshal/Marshal 実装を行っておくことで、リゾルバー内の実装では、任意のクラスのインスタンスとして扱えるようになります。 どのようなクラスにマッピングすべきかは、実装言語に依存します。
簡単に言うと、どこでフォーマットチェックをするかというだけの話なのですが、各リゾルバー内で受信した文字列のフォーマットチェックを行うよりは、カスタムスカラー型ごとの処理として Marshal/Unmarshal 処理が定義されている方が分かりやすいでしょう。
- 参考: GraphQL スキーマ仕様: 列挙型 (enum type) を定義する
- 参考: GraphQL スキーマ仕様: ユニオン型 (Union types) を定義する
- 参考; GraphQL スキーマ仕様: インタフェース型 (interface type) を定義する
関連記事
- GraphQL クエリ仕様: ディレクティブによる条件分岐 (@include, @skip)
- GraphQL クエリ仕様: フィールド名にエイリアスを付ける
- GraphQL スキーマ仕様: @deprecated ディレクティブで非推奨のフィールドを示す
- GraphQL スキーマ仕様: インタフェース型 (interface type) を定義する
- GraphQL スキーマ仕様: スキーマ定義の基本
- GraphQL スキーマ仕様: 型やフィールドに説明文 (description) を記述する
- Apollo Client の fetchMore を自動で呼び出して GitHub GraphQL の100件制限を乗り越える (useAutoFetchMore)