クエリビルダー
スキーマを見ながら add Query／add Child でフィールドを継ぎ足し、GraphQL クエリを段階的に組み立てる操作を説明します。
クエリビルダーとは（概要）
クエリビルダーは、右ペインのスキーマドキュメントを見ながら、クエリを 1 階層ずつ「継ぎ足し」て 組み立てる画面です。add Query でルートのフィールドを差し込み、 各枝に add Child を重ねて内側を展開していきます。組み立て中のクエリは下部の Generated Query パネルに 常時プレビューされ、コピーしてそのまま送信できます。
クエリは環境に依存しません。組み立てたクエリは選択中の環境と組み合わせて送信します （環境の登録・切替）。用語は 主要な用語 を参照してください。
前提
- スキーマの取り込み でスキーマを取り込み済みであること。
- 葉（scalar / enum）と枝（object / interface / union）の違いを理解していること （スキーマドキュメントの参照、主要な用語）。クエリビルダーは同じ判定を使います。
- 「環境変数」と「GraphQL 変数」の違いを理解していること（主要な用語）。 クエリビルダー自体は環境変数の解決を行いません。
画面上の位置
中央ペインの Query タブにクエリビルダーがあります。右ペインにスキーマドキュメント（型カタログ）が
並びます。+ query は右ペインのフィールド行に表示されるので、クリックしたら中央の Query タブで
追加されたルートを確認します（タブが Headers / Auth になっている場合は Query タブに切り替えてください）。
split button（本体ボタン＋▼メニュー）
+ query（右ペインの枝フィールド行）と + child（ビルダーの枝ノード行）は、隣り合う 2 つのボタンからなる
split button です。
- 本体ボタン（
+ query/+ child）: 固定の既定どおりに、その場で確定して挿入します。+ query本体 … 常に子なし（フィールド名だけをルートに追加）+ child本体 … 常に直下スカラーのみ（葉だけを 1 階層挿入）
- ▼ ボタン: 「直下スカラーのみ」「直下すべて」の 2 択メニュー。選ぶとその 1 回だけその粒度を 適用します（固定の既定は変わりません）。
- 葉フィールドの
+ queryには ▼ がありません（展開する子がないため、本体だけのプレーンボタンになります）。
操作手順
1. add Query でルートフィールドを追加する
- 右ペインのスキーマドキュメントで Query 型（または Mutation 型）を開きます。
- ルート型（Query / Mutation。Subscription は対象外）のフィールド行の右端にある
+ query本体を クリックします。 - そのフィールドが中央ペインの Query タブにルートとして追加されます。
+ query 本体は常に子を入れません。 枝フィールドでも中身が空で追加されます（追加のたびに不要な
フィールドを消す手間をなくすための仕様です）。空の枝は GraphQL の文法上 { } と書けないため、
Generated Query では自動的に __typename だけが入ります。追加したら、次の手順で + child を使って
中身を展開してください。
枝フィールドの ▼ を開いて「直下スカラーのみ」「直下すべて」を選ぶと、その 1 回だけ、選んだ粒度で 直下フィールドを入れた状態でルートに追加できます。
2. 挿入の粒度（本体の固定既定と ▼ の一回限り）
以前ツールバーにあった「挿入粒度」の切替（ラジオ）は廃止されました。現在は、本体ボタンの固定既定と、 ▼ の一回限りの上書きだけで粒度を決めます。
| 操作 | 挿入されるもの |
|---|---|
+ query 本体 |
常に子なし（フィールド名のみ） |
+ query の ▼ |
その 1 回だけ「直下スカラーのみ」または「直下すべて」 |
+ child 本体 |
常に直下スカラーのみ（葉 = scalar / enum） |
+ child の ▼ |
その 1 回だけ「直下スカラーのみ」または「直下すべて」 |
▼ メニューの選択肢:
| メニュー表示 | 挿入されるもの |
|---|---|
| 直下スカラーのみ | 直下の葉（scalar / enum）だけ |
| 直下すべて | 直下の葉 ＋ 枝フィールドの名前 |
3. + child で 1 階層を展開する
挿入済みの枝ノード（object / interface 型のフィールド）には + child の split button が表示されます。
- 本体クリック … 常に直下スカラーのみで、その型の直下フィールドを 1 階層挿入します。
- ▼ クリック … 「直下スカラーのみ」「直下すべて」を選ぶと、その 1 回だけその粒度で展開します。
展開した子がさらに枝なら、その子にも + child が現れるので、繰り返しクリックして再帰的に深く伸ばせます。
本体が押せなくても ▼ の「直下すべて」だけは押せることがあります。 葉を持たず枝だけの型では、 本体（直下スカラーのみ）は挿入できる葉が 0 件で無効になりますが、▼ の「直下すべて」は枝の名前を 入れられるため有効です。本体が押せないからといって直下フィールドを一切追加できないとは限らないので、 必ず ▼ も確認してください。両方の粒度で候補が 0 件になったときだけ、本体・▼ とも無効になります。
4. サジェスト入力で 1 フィールドずつ追加する
各枝ノードの子の並びの下に、「+ フィールド追加（打つとサジェスト）」の入力欄があります。
- フィールド名の一部を入力すると、大文字・小文字を区別せず部分一致で候補が出ます（追加済みは除外）。 フォーカスした時点でも全候補が表示されます。
↑↓で候補を移動し、Enterで確定してその 1 フィールドだけを子として追加します。 追加後は入力欄が空になり、続けて次を検索できます。Escで閉じます。マウスで候補行をクリックしても選べます。
5. 操作名（operationName）を設定する
Query タブ上部の「操作名」欄に、生成する GraphQL operation の名前を入力できます（既定 MyQuery）。
トップバーのリクエストタブ名にも反映されます。GraphQL の識別子として無効な文字は自動整形されるため、
どんな入力でも Generated Query は常に構文的に正しい GraphQL になります。
6. Query と Mutation は混在できない
先に追加したルートの種別（Query か Mutation か）で、以後の add Query がロックされます。反対側の
+ query は本体・▼ とも無効になり、カーソルを乗せると次のツールチップが表示されます。
すでに Query のフィールドを追加しているため、異なる種別は追加できません（Query と Mutation は同じ操作に混在できません）
ロックを解除するには、Query タブのルートフィールドを × ですべて削除します（0 件に戻ると、
Query・Mutation どちらの + query も再び選べるようになります）。Query と Mutation を同じ operation に
混在させたクエリはサーバの検証で確実に拒否されるため、この制約があります。
7. フィールドを削除する
各ノード行の右端にある × ボタンをクリックすると、そのノードを削除できます。枝ノードを削除すると、
その配下の子ノードもまとめて削除されます。
8. 引数（arguments）を入力する
フィールドに引数がある場合は、そのノードの引数エリアで「＋ 引数キーを追加」からスキーマ上の引数名を
選び、型別の値欄に入力します。入力すると Generated Query に field(name: value) として出力されます。
- String / ID などはクオート無しで入力します（組み立て時に
"..."へエスケープされます）。 - 値を空に戻すと**未設定（省略）**になり、その引数はクエリに出ません（自動で null や
""にはしません）。 - 必須引数（
型!）が未設定のときは、プレビュー下に警告が表示されます。 - 配列は「＋ 要素」、入力オブジェクトはネストしたキー追加で入力します。
9. 入力モードを切り替える（インライン／変数）
クエリビルダーの上部に 入力モードの切替 [ インライン ｜ 変数 ] があります（リクエストごとに保持されます）。 入力した引数の値そのものはどちらのモードでも共通で、モードは「生成されるクエリの書き方」を切り替えるだけです。
- インライン（既定）… 引数の値をクエリ本文に直接書き込みます（手順 8 のとおり）。その場で試すのに向きます。
- 変数 … トップレベルの引数を
$名前の GraphQL 変数に置き換え、query MyQuery($名前: 型) { … }の形と、 値をまとめた variables（JSON）を生成します。クエリを使い回したり、パラメータ化したクエリとして共有するのに向きます。
変数モードのときの値入力は、ビルダー上部に出る 変数（値を入力） の一覧（変数マトリクス）にまとまります。
各行は $名前 ｜ 型 ｜ 値の入力欄 です。まだ値を入れていない引数は キー名（未設定） と表示され、値を入れると
次の表示から $名前 に変わります（変数名はキー名から自動で付き、同名が衝突するときは id → post_id → id2 の
ように自動で重複を避けます）。入力オブジェクトやリストの引数は、値の入力欄の中で手順 8 と同じように展開して
入力します。二重入力を避けるため、変数モードではツリー側の引数の値欄は「値はマトリクスで入力」という参照表示に
なります。
インラインでも変数でも、標準的なスカラー型では送信したときの実行結果は同じです。モードを切り替えても、入力した 値は失われません。
補足: 独自に定義されたカスタムスカラー型では、まれにインラインと変数で値の受け取り方が異なる場合があります。 また、引数の値に書いた
{{環境変数}}は、送信時に選択中の環境の値へ解決されてから送られます（クエリ本文・variables とも）。 Generated Query の「最終形（解決後）」トグルで解決後の内容を確認でき、履歴や保存には元の{{...}}がそのまま残ります。送信の詳細は クエリの送信とレスポンス を参照してください。
10. Generated Query で確認・コピーする
Query タブ下部の Generated Query パネルに、組み立て中のツリーから生成された GraphQL クエリが常時 プレビューされます。右上の「コピー」ボタンで、表示中のテキストをそのままクリップボードへコピーできます。 ルートが 1 件も無い状態では「コピー」は無効です。
組み立て例
次の架空スキーマを例にします。
type Query { user(id: ID!): User }
type User { id: ID! name: String posts: [Post!]! }
type Post { id: ID! title: String }
| 手順 | 操作 | 結果 |
|---|---|---|
| 1 | user 行の + query 本体 |
user がルートに追加（中身は空 → user { __typename }） |
| 2 | user の + child 本体 |
直下の葉 id name が入る（枝 posts はまだ入らない） |
| 3 | user の + child ▼「直下すべて」 |
この 1 回だけ posts（枝）も追加（子がまだ無く posts { __typename }） |
| 4 | posts のサジェスト欄で title を Enter |
posts の子に title が入る |
このときの Generated Query:
query MyQuery {
user {
id
name
posts {
title
}
}
}
user に必須引数 id: ID! がある場合は、手順 8 の引数エリアで id を追加して値を入れてください
（未設定のまま送信するとサーバ側でバリデーションエラーになります）。
ポイント
- 追加直後の枝が空に見え、
__typenameが入るのは仕様です。+ childでその枝を展開すると、 実際に追加したフィールドに置き換わります。 - 組み立て中のタブ内容は自動保存され、次回起動時やプロジェクト切替時に復元されます。 環境を切り替えてもタブ内容は変わりません（クエリは環境非依存のため）。
- スキーマを再取込してもビルダー内容は消えません。長期保存したいクエリは「コレクションに追加」で 明示保存するか、「コピー」で控えてください。
現時点でできないこと（制限事項）
- union 型を参照するフィールドの
+ child展開は未対応です（常に無効になります）。 - Subscription はルート型として対象外です。
+ queryは Query / Mutation のフィールドにのみ出ます。 - エディタ上でのスキーマ連動補完は未対応です。
うまくいかないときは
| 症状 | 想定される原因 | 対処 |
|---|---|---|
+ query が押せない（薄い表示） |
反対の種別（Query / Mutation）を追加済みでロック中 | ツールチップの理由を確認。混在させたいならルートを全削除して解除する |
+ query を押したのに中身が空 |
仕様（本体は常に子なしで追加） | 追加したノードの + child で中身を展開する |
+ child 本体は無効だが ▼「直下すべて」は押せる |
その型が葉を持たず枝だけを持つ | ▼ を開いて「直下すべて」を選ぶ |
+ child 本体・▼ とも無効 |
直下フィールドを全追加済み、または union 型 | 全追加済みなら対応不要。union 型の展開は未対応 |
| 「コピー」が押せない | クエリビルダーにルートが 0 件 | + query で 1 件以上フィールドを追加する |
覚えのない __typename が入っている |
子を持たない枝への自動補完 | 使いたい枝は + child で展開する |
| 送信（またはコピーして外部実行）で「引数が不足」等になる | 必須引数が未設定 | 手順 8 で必須引数を追加し値を入力する |
関連ドキュメント
- スキーマの取り込み: スキーマの取り込み
- 葉／枝・型カタログ: スキーマドキュメントの参照
- 環境・変数の違い: 環境の登録・切替 / 主要な用語
- 組み立てたクエリの送信: クエリの送信とレスポンス
- 索引に戻る: ユーザーマニュアル目次