Skip to main content

Working with Queries

Learn how to write and execute GraphQL queries to fetch data from APIs.

What is a Query?​

A query is a read operation that fetches data from a GraphQL API. Queries are similar to GET requests in REST APIs, but with more flexibility and power.

Basic Query Structure​

Every GraphQL query follows this structure:

query QueryName {
  fieldName {
    subField
    anotherSubField
  }
}

Simple Example​

query {
  viewer {
    _id
    name
    email
  }
}

Query Components​

Query Name​

Naming your queries helps with debugging and logging:

query GetUserProfile {
  user(id: "123") {
    name
    email
  }
}

Use descriptive names that indicate what the query does (e.g., GetUserProfile, ListItems, SearchProducts).

Field Selection​

You must specify which fields you want to retrieve. GraphQL requires you to select fields down to scalar values:

query {
  item(id: "123") {
    _id          # Scalar (ID)
    title        # Scalar (String)
    price        # Scalar (Float)
    description  # Scalar (String)
  }
}

Nested Fields​

For object types, you must select subfields:

query {
  item(id: "123") {
    _id
    title
    seo {              # Object type - must select subfields
      title
      description
    }
  }
}

Using Arguments​

Fields can accept arguments to filter, paginate, or customize results:

query {
  items(
    pagination: { page: 1, limit: 10 }
    filters: { status: ACTIVE }
  ) {
    items {
      _id
      title
    }
  }
}

Using Variables​

Variables make queries reusable and secure. Always use variables instead of hardcoding values:

query GetItems($page: Int!, $limit: Int!) {
  items(pagination: { page: $page, limit: $limit }) {
    items {
      _id
      title
    }
  }
}

Variables:

{
  "page": 1,
  "limit": 10
}

Variable Types​

Variables must be typed. Common types:

  • String - Text values
  • Int - Integer numbers
  • Float - Decimal numbers
  • Boolean - True/false
  • ID - Unique identifier
  • [Type] - Arrays (e.g., [String])
  • Type! - Required (non-nullable)

Required Variables​

Use ! to mark variables as required:

query GetItem($id: String!) {  # Required
  item(id: $id) {
    title
  }
}

query GetItems($limit: Int) {  # Optional
  items(pagination: { limit: $limit }) {
    items { title }
  }
}

Multiple Queries​

You can request multiple resources in a single query:

query {
  items(pagination: { page: 1, limit: 5 }) {
    items {
      _id
      title
    }
  }
  user(id: "123") {
    name
    email
  }
  collections {
    items {
      _id
      title
    }
  }
}

Aliases​

Use aliases to request the same field multiple times with different arguments:

query {
  firstPage: items(pagination: { page: 1, limit: 10 }) {
    items { title }
  }
  secondPage: items(pagination: { page: 2, limit: 10 }) {
    items { title }
  }
}

Fragments​

Fragments let you reuse field selections:

fragment ItemFields on Item {
  _id
  title
  price
  description
}

query {
  item(id: "123") {
    ...ItemFields
  }
  items {
    items {
      ...ItemFields
    }
  }
}

Common Query Patterns​

Single Item​

query GetItem($id: String) {
  item(id: $id) {
    _id
    title
    price
    description
  }
}

List with Pagination​

query GetItems($pagination: PaginationInput) {
  items(pagination: $pagination) {
    items {
      _id
      title
    }
    pagination {
      page
      pages
      count
      hasMore
    }
  }
}

Nested Data​

query {
  item(id: "123") {
    _id
    title
    collection {
      _id
      title
      items {
        _id
        title
      }
    }
  }
}

Conditional Fields​

Use inline fragments for conditional fields:

query {
  items {
    items {
      _id
      title
      ... on Product {
        sku
        stock
      }
      ... on Service {
        duration
        price
      }
    }
  }
}

Best Practices​

  • Request only what you need - Select only the fields you require to reduce payload size and improve performance
  • Use descriptive query names - Name queries clearly (e.g., GetUserProfile instead of Query1) to help with debugging and logging
  • Always use variables - Use variables instead of hardcoding values to make queries reusable and secure
  • Use fragments for reusability - Create fragments for commonly used field selections to avoid repetition
  • Handle errors - Check for errors in query responses even when HTTP status is 200. See Handling Errors for details

Common Mistakes​

  • Missing required subfields - When querying object types, you must select subfields down to scalar values. For example, if seo is an object, you must select seo { title description } instead of just seo
  • Forgetting variable types - All variables must be typed. Use query GetItem($id: String) instead of query GetItem($id)
  • Not using variables - Avoid hardcoding values in queries. Use variables to make queries reusable and prevent security issues

Summary​

  • Queries are read operations that fetch data
  • Always specify fields down to scalar values
  • Use variables for dynamic values
  • Use descriptive query names for debugging
  • Request only what you need to optimize performance
  • Use fragments to reuse field selections
  • Always handle errors in query responses

Next Steps​