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
  • • 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.

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