GraphQL playground variables guide for testing and debugging

GraphQL Playground variables let you pass dynamic data into your queries and mutations without hardcoding values directly into the query string. You define them once in a dedicated JSON panel at the bottom of the interface, then reference them inside your operation using the $ prefix. This keeps your operations reusable, your data clean, and your testing workflow fast — especially when you need to run the same query against dozens of different inputs.

Introduction to variables

In GraphQL, a variable is a named placeholder declared in your operation signature and resolved at execution time from a separate JSON object. This is fundamentally different from string interpolation — the query document itself never changes, only the data you hand to it. That separation is what makes variables the standard approach for anything beyond a one-off manual test.

GraphQL Playground and GraphiQL both expose this through a split panel layout: the top-left editor holds your query or mutation, and the Query Variables tab at the bottom holds the JSON. When you click Run, both are sent together in a single HTTP POST — the query as query, the variables as variables, and optionally the operation name as operationName.

Setting up query variables

The Query Variables panel is the tab at the bottom-left of GraphQL Playground, directly below the query editor. It accepts standard JSON. If the panel is collapsed, click the tab label to expand it — it will split the left pane horizontally, giving you the query editor on top and the variable editor below.

A common mistake at this step is leaving the Variables panel empty while declaring variables in the query. GraphQL will throw a Variable "$id" of required type "ID!" was not provided error. If a variable is truly optional, declare it without ! and omit it from the JSON — GraphQL will pass null to the resolver.

Using variables in queries

Every variable follows the same three-step pattern: declare it in the operation signature, type it, and use it inside the operation body. The declaration sits inside the parentheses after your operation name. The type must match a scalar or input type defined in your schema.

The $ prefix is required in both the declaration ($id: ID!) and every reference inside the body (user(id: $id)). Omitting it in either place is one of the most common beginner mistakes and produces a clear parse error.

Variable syntax example

Below are two complete examples — a query and a mutation — showing both the operation and the corresponding Variables JSON. These cover the two most common patterns you will encounter in daily development.

Query example: fetching a user by ID. The $id: ID! declaration means the variable is required and must be a valid ID scalar. The exclamation mark prevents the query from running with a null identifier.

query GetUser($id: ID!) {
  user(id: $id) {
    name
    email
    profile {
      avatar
      bio
    }
  }
}

{
  "id": "123"
}

Mutation example: creating a new post. Input objects are declared as a custom input type (CreatePostInput) and passed as a single variable, which is the idiomatic pattern for mutations with multiple fields.

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    publishedAt
  }
}

{
  "input": {
    "title": "Getting started with GraphQL variables",
    "body": "Variables make your operations reusable...",
    "authorId": "456"
  }
}

Notice that for the mutation, the entire payload is nested under a single input key. This matches the $input: CreatePostInput! declaration and is the standard convention for mutation arguments in production schemas.

Best practices

Variables are simple to use but easy to misuse. The patterns below reflect conventions from production GraphQL APIs and will make your operations easier to maintain, test, and hand off to colleagues.

Use descriptive names. $userId, $searchTerm, and $pageLimit are immediately readable. $input, $data, and $val require the reader to trace through the entire query to understand what they carry. Name variables after the data they represent, not the role they play.

Always declare types explicitly. Even when GraphQL could infer a type, the explicit declaration acts as inline documentation and enables Playground’s autocomplete and inline error highlighting.

Use default values for optional parameters. A declaration like $limit: Int = 20 means your query runs correctly even when the caller omits limit from the JSON, reducing defensive null-handling in your resolvers.

Common use cases

The patterns below account for the majority of variable usage in real-world GraphQL APIs. Understanding them gives you a mental library to draw on whenever you hit a new testing scenario in Playground.

Filtering with dynamic criteria. Pass filter parameters as variables instead of building separate queries for each filter state. For example, a product listing can use $category: String and $minPrice: Float together, and you test every combination by changing only the JSON.

Cursor-based pagination. The Relay pagination convention uses $first: Int and $after: String (a cursor). In Playground, you grab the endCursor from a response, paste it into the Variables JSON as "after", and immediately fetch the next page — no query editing needed.

query GetProducts($first: Int = 10, $after: String, $category: String) {
  products(first: $first, after: $after, category: $category) {
    edges {
      node {
        id
        name
        price
      }
    }
    pageInfo {
      endCursor
      hasNextPage
    }
  }
}

{
  "first": 10,
  "after": "cursor_abc123",
  "category": "electronics"
}

Directive conditions. The built-in @include(if: Boolean) and @skip(if: Boolean) directives accept variables directly, letting you toggle entire field sets from the JSON panel — useful when testing conditional UI states.