GraphQL Queries and Mutations

Advanced Query Techniques

Query Variables

Variables allow clients to pass dynamic values to queries, making them reusable and more maintainable:

// Query definition with variables
query GetBook($id: ID!, $includeAuthor: Boolean!, $includeReviews: Boolean!) {
  book(id: $id) {
    id
    title
    year
    # Conditional field inclusion
    author @include(if: $includeAuthor) {
      name
      bio
    }
    # Conditional field inclusion
    reviews @include(if: $includeReviews) {
      rating
      text
    }
  }
}

// Variables provided separately (typically as JSON)
{
  "id": "123",
  "includeAuthor": true,
  "includeReviews": false
}
                

Variables offer several advantages:

• Separate query logic from values
• Avoid string concatenation and injection issues
• Improve query reusability
• Enable caching and persisted queries

Directives

Directives provide a way to dynamically change query execution based on variables:

• @include(if: Boolean): Include field only if argument is true
• @skip(if: Boolean): Skip field if argument is true
• @deprecated(reason: String): Mark field as deprecated
• Custom directives: Implement your own directives for special behaviors

query GetUserData($includePrivate: Boolean!, $skipInternal: Boolean!) {
  user(id: "123") {
    id
    name
    email
    
    # Only include if variable is true
    phoneNumber @include(if: $includePrivate)
    address @include(if: $includePrivate) {
      street
      city
      country
    }
    
    # Skip if variable is true
    internalNotes @skip(if: $skipInternal)
    
    # Field is marked as deprecated
    username @deprecated(reason: "Use 'name' instead")
  }
}
                

Aliases

Aliases allow you to query the same field multiple times with different arguments:

query CompareTwoBooks {
  firstBook: book(id: "123") {
    title
    author {
      name
    }
    rating
  }
  
  secondBook: book(id: "456") {
    title
    author {
      name
    }
    rating
  }
}

// Response:
{
  "data": {
    "firstBook": {
      "title": "The Great Gatsby",
      "author": { "name": "F. Scott Fitzgerald" },
      "rating": 4.2
    },
    "secondBook": {
      "title": "To Kill a Mockingbird",
      "author": { "name": "Harper Lee" },
      "rating": 4.3
    }
  }
}
                

Fragments

Fragments are reusable units of a query that help reduce redundancy and improve maintainability:

# Define a fragment on the Book type
fragment BookDetails on Book {
  id
  title
  year
  genre
  summary
}

fragment AuthorDetails on Author {
  id
  name
  bio
  birthDate
}

# Use fragments in queries
query GetBooksWithAuthors {
  books {
    ...BookDetails
    author {
      ...AuthorDetails
    }
  }
  
  featuredBook {
    ...BookDetails
    coverImage
    author {
      ...AuthorDetails
      profileImage
    }
  }
}
                

Fragments are particularly useful for:

• Avoiding field duplication
• Maintaining consistency across queries
• Making complex queries more readable
• Enabling component-based data fetching in clients like Relay

Inline Fragments and Type Conditions

When querying interfaces or unions, inline fragments with type conditions allow you to request type-specific fields:

# Schema with interface
interface SearchResult {
  id: ID!
  title: String!
}

type Book implements SearchResult {
  id: ID!
  title: String!
  author: Author!
  pages: Int
}

type Movie implements SearchResult {
  id: ID!
  title: String!
  director: String!
  duration: Int
}

type Query {
  search(term: String!): [SearchResult!]!
}

# Query with inline fragments
query Search($term: String!) {
  search(term: $term) {
    id
    title
    # Type-specific fields
    ... on Book {
      author {
        name
      }
      pages
    }
    ... on Movie {
      director
      duration
    }
  }
}
                

                    graph TD
                    A[Query] --> B[SearchResult Interface]
                    B --> C[Common Fields: id, title]
                    B --> D[Book Type]
                    B --> E[Movie Type]
                    D --> F[Book-specific fields: author, pages]
                    E --> G[Movie-specific fields: director, duration]