Writing Queries

Two Ways to Build Queries

You can write GraphQL queries in two ways:

VisualSchema Explorer

Browse the schema tree and click checkboxes to select fields. The query is generated automatically. Best for exploring APIs and learning what's available.

ManualQuery Editor

Type GraphQL queries directly with syntax highlighting. Full control over the query structure. Best for complex queries with aliases, fragments, or directives.

Tip: Start with the Schema Explorer to build a basic query, then switch to the Query Editor to fine-tune it.

Query Editor

The Query Editor is in the bottom section of the Query tab. It provides:

  • Syntax highlighting - Keywords, fields, and types are color-coded
  • Line numbers - Helps identify error locations
  • Copy button - Copy the entire query to clipboard
query GetUsers($limit: Int, $offset: Int) {
users(limit: $limit, offset: $offset) {
id
name
email
posts {
title
createdAt
}
}
}

Query Variables

Variables allow you to parameterize your queries. Instead of hardcoding values, you define variables and pass their values separately:

Query with Variables

query GetUser($id: ID!) {
user(id: $id) {
id
name
}
}

Variables (JSON)

{
"id": "user-123"
}

Why Use Variables?

  • • Cleaner queries - Separate data from query structure
  • • Reusability - Same query, different values
  • • Security - Prevents injection attacks
  • • Caching - Servers can cache parameterized queries

Variables Tab

Edit query variables in the Variables tab:

{
"limit": 10,
"offset": 0,
"filter": {
"status": "active",
"role": "admin"
}
}
  • • Variables must be valid JSON, and invalid JSON is highlighted with inline warnings
  • • If the JSON does not parse, the variables block is left out of the request rather than sent broken, so a server complaining about a missing variable usually means a stray comma here
  • • Keys must match variable names in the query (without $)
  • • Use the Format button to pretty-print JSON
  • • When using Schema Explorer, variables are auto-generated from argument inputs

Operation Names

Operation names are optional but recommended. They identify your query:

Anonymous (not recommended)

{
users { id name }
}

Named (recommended)

query GetAllUsers {
users { id name }
}

Named operations help with debugging, logging, and are required when a document contains multiple operations.

Several Operations in One Document

A GraphQL request runs exactly one operation. When your document defines more than one named operation, a picker appears next to the Send button and your choice is sent as the operationName in the request body. With a single operation there is nothing to choose, so the picker stays hidden and the name is sent automatically when the operation has one.

Generated Queries Are Named Too

Queries built in the Schema Explorer are named after the first field you selected (query Users, mutation CreateUser), so selecting from more than one root still produces a valid document and your server logs show something you can search for.

Fragments

Fragments let you reuse field selections across queries:

# Define a fragment
fragment UserFields on User {
id
name
email
}
# Use it in a query
query {
currentUser {
...UserFields
}
user(id: "123") {
...UserFields
createdAt
}
}

Fragments are written manually in the Query Editor. The Schema Explorer doesn't generate fragments automatically.

Directives

Directives modify query execution. Common built-in directives:

@includeConditionally include a field

query GetUser($withEmail: Boolean!) {
user(id: "123") {
id
name
email @include(if: $withEmail)
}
}

@skipConditionally skip a field

query GetUser($hideEmail: Boolean!) {
user(id: "123") {
id
name
email @skip(if: $hideEmail)
}
}

Best Practices

Request Only What You Need

Only select fields you'll actually use. Over-fetching wastes bandwidth and server resources.

Use Variables for Dynamic Values

Never hardcode IDs, pagination values, or user input directly in queries.

Name Your Operations

Use descriptive names like GetUserProfile, CreateComment, UpdateSettings.

Use Fragments for Repeated Selections

If you're selecting the same fields in multiple places, extract them into a fragment.

Schema ExplorerUnderstanding Responses