Arguments in GraphQL — Complete Guide

In this tutorial, you will learn about Arguments in Graphql. We cover key concepts, practical examples, and best practices to help you master this topic.

Arguments let clients parameterize GraphQL fields to filter, sort, paginate, or transform data. Both root query fields and nested object fields can accept arguments, making the API flexible and efficient.

What You'll Learn

• Defining arguments on fields
• Required and optional arguments
• Default argument values
• Argument validation and transformation
• Arguments on nested fields

Why It Matters

Arguments make GraphQL APIs expressive. Clients can request specific data without server-side endpoints for each combination. Proper argument design reduces the number of fields in your schema.

Real-World Use

GitHub's search query accepts a query string argument for full-text search across repositories. The Repository field accepts owner and name arguments instead of exposing flat fields.

flowchart LR
    Field[Field: products] --> Args[Arguments]
    Args --> first[first: Int]
    Args --> after[after: String]
    Args --> category[category: ID]
    Args --> priceRange[priceMax: Float]
    Field --> Return[Return: [Product!]!]

Teacher Mindset

Arguments should feel like function parameters. Use required arguments when the field cannot return meaningful data without them. Use optional arguments with defaults for filtering and pagination.

Code Examples

# Example 1: Arguments on query fields
type Query {
  book(id: ID!): Book
  books(
    category: Category
    minPrice: Float
    maxPrice: Float
    first: Int = 10
    offset: Int = 0
  ): [Book!]!
}

# Example 2: Arguments on nested fields
type Author {
  id: ID!
  name: String!
  books(
    publishedAfter: Date
    genre: Genre
    sortBy: String = "title"
  ): [Book!]!
}

# Example 3: Arguments with custom scalar validation
type Query {
  users(
    search: String
    role: UserRole
    isActive: Boolean
    sort: SortInput
    pagination: PaginationInput!
  ): UserConnection!
}

input SortInput {
  field: String!
  direction: SortDirection = ASC
}

Common Mistakes

• Adding too many optional arguments that make queries hard to read
• Using arguments where field-specific types and connections fit better
• Making arguments required when sensible defaults exist
• Ignoring input validation for argument values
• Not documenting argument behavior in descriptions

Practice

1. Add a search argument to a products query that filters by name.
2. Create a pagination argument set with first and offset parameters.
3. Add a sort argument to a users query with field and direction.
4. Define a nested argument on a Category type that filters products by price range.
5. Challenge: Design a filtering system using a FilterInput type with AND/OR combinators.

FAQ

Mini Project

Add comprehensive argument support to your library schema. Add search, pagination, and sort arguments to the books query. Add filtering arguments to the author.books nested field.

What's Next

Next, you will learn about directives in GraphQL for annotating schema elements and transforming query behavior.