GraphQL Query Builder

Build a GraphQL query or mutation by clicking fields on a sample User and Post schema, with arguments and variables. Good for learning the syntax.

The interactive tool loads here when JavaScript runs.

About this tool

What is the GraphQL Query Builder?

The GraphQL Query Builder writes a GraphQL operation for you as you click fields. Choose Query or Mutation, optionally name the operation and declare variables, then toggle fields on the sample User and Post types. Build Query prints a correctly indented document you can copy or download as query.graphql.

Fields that return objects, such as User.posts and Post.author, are given a small selection of subfields automatically, because GraphQL rejects an object field without one. Each selected field also gets an arguments box, so you can add first: 10 or id: $id without remembering where the parentheses go.

The field list is a fixed teaching schema, not your API. It is meant for learning how selection sets, arguments, aliases of the root field and variables fit together; for your own schema, write the query in the GraphQL Playground and check it with the Complexity Analyzer.

  • Query and mutation modes
  • Operation name and variable declarations
  • Automatic sub-selections for object fields
  • Per-field arguments
  • Copy, download as .graphql and a fullscreen mode
Read the guide: GraphQL Schemas and Queries: Validation, Types and Query Cost

Updated

How to use the GraphQL Query Builder

  1. Pick the Query or Mutation tab.
  2. Optionally enter a Query Name such as GetUser, and Variables such as $id: ID!, $limit: Int.
  3. Click fields under User and Post to select them. A selected field shows an arguments box; type arguments like id: $id or first: 5 without parentheses.
  4. Press Build Query, then Copy or Download the result from the Generated Query panel.

Worked example

A user with their posts

Input

Query Name: GetUser, Variables: $id: ID!, fields User.name and User.posts (arguments: first: 5)

Output

query GetUser($id: ID!) {
  user {
    name
    posts(first: 5) {
      id
      title
    }
  }
}

posts returns a list of Post objects, so the builder adds id and title as a default sub-selection. Add id: $id to the root field yourself in your real API, where user usually takes an id argument.

Background and insight

A GraphQL query mirrors the shape of the JSON you want back. Every field that returns an object needs its own braces with at least one field inside; only scalars and enums (String, Int, ID, Boolean, enums) can appear bare. Forgetting this is the most common first error, reported by servers as "Field 'posts' of type '[Post]' must have a selection of subfields".

Variables are declared once at the top, with a $ prefix and a type ($id: ID!), and then used anywhere an argument value is expected. The ! means the variable is required. Naming operations (query GetUser) costs nothing and pays off later: names show up in server logs, APM traces and persisted-query registries.

Common use cases

  • Learning GraphQL syntax

    See how variables, arguments and nested selection sets are written without fighting syntax errors.

  • Teaching a team

    Show the difference between a scalar field and an object field that needs a sub-selection during onboarding.

  • Drafting a query skeleton

    Generate the indentation and braces for a two-level query, then rename fields to match your API.

Tips and limitations

  • The available fields are a fixed sample schema. Rename fields in the output to match your API, then run it in the GraphQL Playground.
  • Type arguments without the surrounding parentheses; the builder adds them (and will not double them if you do type them).
  • A declared variable that is never used is a validation error on most servers, so either use it in an argument or delete it.
  • Mutations normally take an input argument, for example createUser(input: $input). Select fields to choose what the mutation returns.

Sources and further reading

  1. Queries, GraphQL Foundation. Fields, arguments, variables and named operations
  2. GraphQL Specification, October 2021 edition, GraphQL Foundation. The rule that object fields need a selection set
  3. Mutations, GraphQL Foundation. How mutations differ from queries

Frequently asked questions

Can the GraphQL Query Builder load my own schema?

No, it uses a fixed sample schema with User and Post types. It is designed for learning and drafting the shape of a query. To work against your API, paste the drafted query into the GraphQL Playground and adjust field names.

Why does the query builder add id and title under posts?

Because posts returns Post objects, and GraphQL requires every object field to have a selection set. Leaving it bare would produce a query the server rejects, so the builder adds a minimal default you can edit.

What is the difference between a query and a mutation in GraphQL?

A query reads data and the server may run its root fields in parallel. A mutation changes data, and its root fields run one after another in the order written. Both select the fields they return in the same way.

Where do I put variables in a GraphQL query?

Declare them in parentheses after the operation name, like query GetUser($id: ID!), then use $id as an argument value inside. Send the actual values separately as a JSON variables object, which the GraphQL Playground has a tab for.

Is anything sent to a server when I build a query?

No. The builder only assembles text in your browser. Nothing is executed until you paste the query into a client such as the GraphQL Playground and run it against an endpoint.

Is there an in-depth guide to the GraphQL Query Builder?

Yes. “GraphQL Schemas and Queries: Validation, Types and Query Cost” covers the background, how it works, common pitfalls and worked examples. Read the full guide.