When to Use Fragments in GraphQL: Clear Guide and Examples

Use fragments in GraphQL to reuse parts of queries or mutations that repeat across different requests. They help keep your queries clean, reduce errors, and make maintenance easier by defining common fields once and including them wherever needed.

How It Works

Think of GraphQL fragments like reusable building blocks for your queries. Instead of writing the same set of fields multiple times, you define a fragment once and then include it wherever you want. This is similar to creating a template or a shortcut for repeated parts.

When you send a query with fragments, the GraphQL server replaces the fragment references with the actual fields before executing the query. This keeps your queries shorter and easier to read, especially when dealing with complex data structures.

Example

This example shows a fragment named UserDetails that fetches common user fields. The fragment is then used in two different queries to avoid repeating the same fields.

graphql

fragment UserDetails on User {
  id
  name
  email
}

query GetUser1 {
  user(id: "1") {
    ...UserDetails
    createdAt
  }
}

query GetUser2 {
  user(id: "2") {
    ...UserDetails
    lastLogin
  }
}

Output

{
  "data": {
    "user": {
      "id": "1",
      "name": "Alice",
      "email": "[e-mail]",
      "createdAt": "2023-01-01T12:00:00Z"
    }
  }
}

When to Use

Use fragments when you have fields that appear in multiple queries or mutations. This helps avoid repeating the same field list and reduces mistakes if you need to update the fields later.

For example, if you have a user profile with many fields and you request it in different parts of your app, define a fragment for the user fields. Then include that fragment in all queries that need user data.

Fragments are also useful when working with interfaces or unions to fetch common fields across different types.

Key Points

• Fragments let you reuse query parts to keep code DRY (Don't Repeat Yourself).
• They make queries easier to read and maintain.
• Use fragments for repeated fields across queries or mutations.
• Fragments help when querying interfaces or unions with shared fields.

Key Takeaways

Use fragments to reuse common fields in multiple GraphQL queries or mutations.

Fragments keep your queries clean, shorter, and easier to maintain.

They reduce errors by centralizing field definitions in one place.

Fragments are especially helpful for complex or repeated data structures.

Use fragments when querying interfaces or unions to fetch shared fields.