variables (graphql)
gpt-5.icon
GraphQL の variables（変数） は、クエリやミューテーションをより柔軟に・安全に使うための仕組みです。
SQL のプレースホルダ (?) や REST のパラメータのような役割を果たします。
🧩 1. 変数の目的
code:graphql
query {
user(id: "123") {
name
}
}
しかしこれだと、値を動的に変更したい場合（例：ユーザーIDがリクエストごとに違う）に、
クエリ文字列を都度書き換えないといけません。
そこで登場するのが variables です。
🧠 2. 変数の基本構文
GraphQL では変数を使うとき、次の3つの場所に登場します：
1. クエリ定義内の宣言
2. クエリ内での参照
3. HTTP リクエストの variables フィールドで値を渡す
例
code:graphql
query GetUser($id: ID!) {
user(id: $id) {
name
email
}
}
そして、リクエスト時に以下のように変数を渡します：
code:json
{
"id": "123"
}
この JSON は通常、HTTP POST の body に含められます（例：Apollo Client, GraphiQL などで送信）。
🧾 3. 型システムとの関係
変数の宣言には必ず 型指定 が必要です。
（GraphQL では型安全性が非常に重要です）
例：
table:_
宣言 意味
$id: ID! ID 型で必須
$limit: Int Int 型で任意
$filter: UserFilterInput 入力オブジェクト型
code:graphql
query SearchUsers($limit: Int, $filter: UserFilterInput) {
users(limit: $limit, filter: $filter) {
name
}
}
🧱 4. Variables の送信フォーマット（HTTP）
GraphQL サーバーに送信する際は、JSON 形式で次のように送ります：
code:json
{
"query": "query GetUser($id: ID!) { user(id: $id) { name } }",
"variables": { "id": "123" }
}
GraphQL Playground や Apollo Client なども内部的にはこの形式です。
🔒 5. 利点
table:_
利点 説明
再利用性 クエリ定義を固定し、値だけ動的に変えられる
セキュリティ 値をエスケープ済みで扱うため、インジェクション対策になる
型安全 GraphQL スキーマに基づいて静的に型チェックできる
キャッシュ効率 クエリ文字列が固定されるためキャッシュキーが安定する（Apollo など）
🧮 6. 実践例（mutation）
ミューテーションでも同様です：
code:graphql
mutation CreateUser($input: CreateUserInput!) {
createUser(input: $input) {
id
name
}
}
送信時の variables:
code:json
{
"input": {
"name": "Taro",
"email": "taro@example.com"
}
}
⚙️ 7. デフォルト値
変数にはデフォルト値を設定できます：
code:graphql
query GetUsers($limit: Int = 10) {
users(limit: $limit) {
id
name
}
}
この場合、variables に limit が渡されなければ自動的に 10 が使われます。