hidekazu-konishi.com

How to Use This GraphQL Query Builder & Formatter

1. Paste SDL: Drop your GraphQL SDL into the left pane (or upload a .graphql / .gql file), then click Parse Schema. The tool will list every field of Query, Mutation, and Subscription root types as a checkbox tree.
2. Pick an Operation Type: Switch between Query, Mutation, and Subscription tabs to see the relevant root fields.
3. Tick Fields: Check the fields and sub-fields you want. For composite fields, use the Show ... fields disclosure to expand nested object types.
4. Build Query: Click Build Query to generate a complete operation with auto-generated $variable: Type! placeholders for required arguments.
5. Format / Minify / Unminify: Paste any existing operation into the right pane and use the format buttons. Format pretty-prints with the chosen indentation; Minify compresses to a single line; Unminify re-expands a minified operation.
6. Validate: With a schema parsed, click Validate to check the operation against the SDL. Without an SDL, validation is skipped with an info message.
7. Extract Fragments: When the same selection set appears two or more times in an operation, this command replaces the duplicates with a named ...Fragment reference to keep the document DRY.
8. Copy / Clear: Use Copy Output to copy the formatted result and Clear to reset everything.

Pro Tip: Press Ctrl+Enter (Cmd+Enter on Mac) inside either pane to trigger the relevant action: Parse Schema in the SDL pane, Format in the operation pane.

About GraphQL SDL and Operations

GraphQL is a query language for APIs and a runtime for executing those queries against typed schemas. Schemas are defined in SDL (Schema Definition Language), which describes the available types, fields, arguments, and root operation types.

• Object & Interface Types: type and interface declarations describe composite types with selectable fields.
• Scalars: Int, Float, String, Boolean, ID are built-in. Custom scalars can be declared via scalar.
• Enums: enum declarations enumerate a fixed set of named values.
• Unions: union declarations express that a field returns one of several object types.
• Input Types: input types are used as structured argument values for mutations and queries.
• Operations: query, mutation, and subscription are the three root operation types. Variables are declared as $name: Type!.
• Fragments: fragment Name on Type { ... } lets you reuse selection sets across multiple places.

Features

• 🔍 SDL-Driven Tree Builder: Parse your schema and pick fields with checkboxes — no manual typing of long selection sets.
• ✨ Auto Argument Variables: Required arguments become $variable: Type! placeholders automatically.
• 📝 Format / Minify / Unminify: Configurable indentation (2 spaces, 4 spaces, tab) for readable output, or compact single-line minified form.
• ✅ Schema-Aware Validation: Catch unknown fields, missing required arguments, and selection-set mismatches against the SDL.
• 🧩 Fragment Extractor: Detect repeated selection sets and replace them with reusable ...FragmentName spreads.
• 🎨 Syntax Highlighting: Color-coded output for keywords, names, variables, strings, numbers, comments, and punctuation.
• 📑 Three Operation Types: Query, Mutation, and Subscription each get their own root tree.
• 🌌 Interfaces & Unions: Inline fragments (... on Type) preserved when formatting.
• 📁 File Drag & Drop: Drop .graphql / .gql / .txt SDL files up to 5 MB.
• 📋 Examples Included: 4 ready-to-load presets covering objects, interfaces, unions, enums, and inputs.
• 🔒 Privacy First: Everything runs locally — no schema, query, or fragment is ever uploaded.
• 📱 Mobile Friendly: Responsive layout collapses to a single column at narrow widths.
• ⌨️ Keyboard Shortcut: Ctrl+Enter (Cmd+Enter) to format / parse.

Common Use Cases

• API Exploration: Quickly produce a working query template from a freshly downloaded schema, without launching a full GraphiQL/Playground instance.
• Code Review: Standardize indentation across a team's .graphql documents.
• Refactoring: Extract repeated selection sets into reusable fragments to keep operation files DRY.
• Onboarding: Show new developers how a GraphQL schema is shaped and how variables flow into operations.
• Debugging: Beautify minified GraphQL captured from network logs to read it more easily.
• Documentation: Format GraphQL examples for inclusion in technical articles and READMEs.

Important Notes

• This tool intentionally does not send IntrospectionQuery to remote endpoints (CORS would block it for many APIs and we want zero network egress regardless). Paste the SDL manually instead.
• The validator covers fields, required arguments, fragment spread targets, and selection-set shape. It does not deeply check enum values, custom scalar types, or directive arguments — treat its output as a fast first pass, not a substitute for your server-side validator.
• Directives in SDL are tokenised and skipped during parsing; they are preserved in the operation document but not re-emitted by the generator.
• The fragment extractor uses a structural shape match (same field names, args, and sub-shapes under the same parent type). It will not extract a fragment that is materially different across call sites.
• GraphQL specification reference: spec.graphql.org/October2021 (October 2021 edition).
• This tool uses a custom hand-written GraphQL parser/printer rather than the graphql-js library, prioritizing zero external dependencies and offline capability. The custom implementation supports the GraphQL spec features needed for query/mutation/subscription/fragment building, formatting, validation, and minification. If you need full graphql-js feature parity (e.g., advanced type coercion, custom directives processing), use the official graphiql or Apollo Studio.