Lecture 291: Fragments and Their Use in GraphQL

Fragments (or Fragments) in GraphQL are blocks of code that let you reuse specific groups of fields in queries.

The duplication problem in queries

Suppose we have a schema that represents a User entity with fields id, name, email, and profilePicture. Say we want to fetch info about post authors and comment authors. The query might look like this:

query GetPostsAndComments {
  posts {
    id
    title
    author {
      id
      name
      email
      profilePicture
    }
  }
  comments {
    id
    text
    author {
      id
      name
      email
      profilePicture
    }
  }
}

Notice that the user fields block (author) is repeated twice.

Not only does that look bulky, it also invites mistakes: if we need to add or change a field, we’ll have to update it everywhere (and good luck not forgetting one).

Solution: using fragments

Fragments let you pull the common part into a separate block so you can reuse it. Here’s how you could rewrite the query above using fragments:

query GetPostsAndComments {
  posts {
    id
    title
    author {
      id
      name
      email
      profilePicture
    }
  }
  comments {
    id
    text
    author {
      id
      name
      email
      profilePicture
    }
  }
}

Nice, right? The UserFields fragment defines the list of fields you can reuse again and again in any query or mutation that deals with the User entity.

Syntax and structure of fragments

A fragment is declared using the fragment keyword, followed by its name, the type it applies to, and the list of fields:

fragment FragmentName on Type {
  field1
  field2
  ...
}

To use a fragment inside a query, just reference its name prefixed by three dots (...):

{
  entity {
    ...FragmentName
  }
}

Let’s take another example. We have a Book type that describes books:

type Book {
  id: ID!
  title: String!
  author: User!
  publishedYear: Int
}

If a query needs a list of books and their authors, we can declare a fragment for the author:

fragment AuthorFields on User {
  name
  email
}

query GetBooks {
  books {
    id
    title
    author {
      ...AuthorFields
    }
    publishedYear
  }
}

This way we avoid having to list the author fields (name, email) in every query.

Benefits of using fragments

1. Less code duplication
   The fewer copies of the same code, the lower the chance of bugs and inconsistencies.
2. Easier maintenance
   Updating or adding a field in a single fragment automatically affects all queries that use it.
3. Cleaner, more readable queries
   Queries become shorter and easier to understand.
4. More consistency
   A single fragment that defines a specific field structure ensures all queries use the same data.

Limitations and tips for working with fragments

While fragments are useful, it’s important to understand their limits:

• Fragments only work within a single type or interface. If you want to reuse a fragment across different types, you’ll need to define separate fragments for each type.
• Too many fragments can make the schema structure harder to follow. Don’t fragment everything. Use fragments for big, frequently repeated groups of fields.

Practice: Creating and using fragments

Step 1: Let's create a simple GraphQL schema

type User {
  id: ID!
  name: String!
  email: String!
}

type Comment {
  id: ID!
  text: String!
  author: User!
}

type Query {
  comments: [Comment!]!
}

Step 2: Let's write a fragment for User

fragment UserBasicInfo on User {
  id
  name
  email
}

Step 3: Use the fragment in a query

query GetCommentsWithAuthors {
  comments {
    id
    text
    author {
      ...UserBasicInfo
    }
  }
}

Step 4: Add a new query

Suppose we want to add another query that shows the list of users. The fragment comes in handy again:

query GetAllUsers {
  users {
    ...UserBasicInfo
  }
}

Useful tools for working with GraphQL fragments

1. GraphQL Playground
   If you’re developing a GraphQL API, Playground helps you test queries and fragments in a friendly UI.
2. Apollo Client
   Apollo automatically supports caching based on fragments. That’s especially useful on the frontend.

Final practice

Say the User type gets a new field profilePicture. You only need to update the fragment:

fragment UserBasicInfo on User {
  id
  name
  email
  profilePicture
}

Now that update will be reflected in all queries that use the fragment. Isn’t that awesome?

The next lesson will cover more advanced and powerful approaches, like batch loading (Batch Loading). But before moving on, make sure fragments make sense to you and you’re ready to use them in real projects!