GraphQL Variables Guide: How to Pass Variables in GraphQL Queries Like a Pro

GraphQL is powerful because it lets you request exactly the data you want. But hardcoding values into your queries isn't scalable. That’s where GraphQL variables come in.

This guide will teach you how to use variables in GraphQL. What they are, why they matter, and how to use them properly. Whether you’re working in GraphQL Playground, Postman, or a frontend app, you’ll learn how to write dynamic queries that are cleaner and safer.

---

What Are GraphQL Variables?

Variables in GraphQL are dynamic values you pass to a query, so you don’t have to hardcode arguments. Think of them as parameters you define once and reuse.

This improves:

• Reusability: You can change the values without editing the query.

• Security: Avoids issues like query injection.

• Clarity: Makes queries easier to read and maintain.

---

GraphQL Without Variables (The Hard Way)

Here’s a query with the value hardcoded:

query {
  post(id: "123") {
    title
    body
  }
}

This works, but you have to rewrite the query every time you want a different post.

---

GraphQL With Variables (The Better Way)

Here’s the same query using a variable:

query GetPost($postId: ID!) {
  post(id: $postId) {
    title
    body
  }
}

And in the variables panel (e.g., in Playground or Postman):

{
  "postId": "123"
}

This lets you reuse the query and change only the data input.

💡 If you're using Agility CMS, this is useful when querying for dynamic content like blog posts, pages, or product IDs.

---

How to Use Variables in GraphQL Playground

GraphQL Playground (built into Agility CMS and other platforms) includes a variables panel where you pass JSON input.

Step-by-step:

1. Define variables in the query:

query GetAuthor($id: Int!) {
  author(id: $id) {
    name
    bio
  }
}

2. Add this to the variables panel:

{
  "id": 5
}

3. Hit "play" to execute the query with that input.

---

You Need to Define Variable Types Clearly. Here are Common Types:

ID!

• A unique string or number (non-nullable)

Int

• Integer

Float

• Decimal

String

• Text

Boolean

• true/false

[Type]

• Array of values

Example with multiple variables:

query FilterPosts($authorId: ID!, $tag: String) {
  posts(authorId: $authorId, tag: $tag) {
    title
  }
}

And variables:

{
  "authorId": "456",
  "tag": "GraphQL"
}

Variables with Mutations

Variables work the same way with mutations (writes).

Example:

mutation CreateComment($postId: ID!, $content: String!) {
  addComment(postId: $postId, content: $content) {
    id
    content
  }
}

Variables:

{
  "postId": "789",
  "content": "This is great!"
}

When to Use GraphQL Variables

Use variables when:

• You’re running the same query with different inputs.

• You want cleaner code and avoid repetition.

• You’re building a frontend or using tools like Next.js with Agility CMS.

If you're using Agility CMS's GraphQL API, it's smart to use variables when filtering lists, fetching dynamic routes, or building multi-language content pages.

---

Troubleshooting Tips

• Error: Variable "$id" of required type "ID!" was not provided.
  

  • Make sure your variables JSON includes the key.

• Error: Expected value of type "Int", found "abc".
  

  • You're sending a string where an integer is expected. Match types!

Check types in the Docs Explorer inside Playground to see what inputs your query expects.

---

Summary

Using GraphQL variables is one of the best ways to keep your queries clean, safe, and flexible. With tools like Agility CMS and GraphQL Playground, you can write powerful dynamic queries in minutes.

Want to Try It Out?

• Explore the schema in the Agility GraphQL API Docs

• Set up a Next.js project using variables to load dynamic content

• Learn more about content modeling for flexible APIs

Sign up for free and test your first GraphQL query with variables today.