How to query your schema with GraphQL fragments

In this short article we will go through the concept of fragments and how you can reduce the code of your queries and match the exact data needs for your UI.

First, we have to answer the question, what is a fragment? A fragment is basically a reusable piece of query. In GraphQL, you often need to query for the same data fields in different queries. The code to define these fields has to be written multiple times, leading to more errors. By reusing this code, we can be more efficient with our time and reuse these pieces of query logic on different queries. But how we can use it in GraphQL? Let’s say we want to use the same query as in this article on aliases. You can start with cloning this repository

git clone -b feature/4-graphql-aliases
Checkout the upcoming free GraphQL language course with in browser exercices
From upcoming GraphQL Language course

follow the readme, start the server and then go to the /graphiql address. You should then be able to execute the query where the aliases concept is used:

We can see, there’s still room for improvement, as the fields of each query are repeated multiple times. Since they are the same selection set, we can define the fields just once then reference them as needed. For that purpose we can use a fragment. Every fragment consists of different parts. Let’s take a look at this example of a simple fragment:

Each fragment contains the name of the fragment (userFields), to what type we are applying this fragment (User) and the selection set (id, firstName, lastName, phone and username).

Now we can rewrite the getUsers query with the fragment and spread operator.

The results are the same, but in terms of refactoring and code reuse, there are many advantages to writing queries this way.

The other type of fragments is the so-called inline fragment. This is useful for queries in which we have to resolve the type at runtime. This is used when we need to implement one of the abstract types in GraphQL: GraphQLUnion or GraphQLInterface. The most common example of GraphQLInterface is the node interface used in Relay.js. GraphQLUnion is typically used for search implementation in GraphQL. When we query for these types, we have to use an inline fragment to conditionally execute. This query illustrates how this inline fragment can look:

Statements on User and on Company are the type conditions. With type conditions we are able to apply each fragment on different type in the schema even that both types User and Company have different fields.

In other cases, the fragments are also frequently used in frontend caching clients like relay or apollo. In relay we have the so-called fragment container, which defines the component’s data requirements of the component. In the apollo-client, we use the concept of fragments for the so-called queries collocation. Fragments in these caching clients are basically perfect matches for the data needs of the UI components. This can be used to our advantage for static typing with flow or typescript. We can generate flow or typescript definitions from our GraphQL schema and use these definitions as the prop type definition for our UI component. One of the best tool for this is apollo codegen.

Did you like this post? Then clap for this article as it makes it easier for others to find it. The repository with the examples and project setup can be cloned from this Github branch. You can get early access to upcoming free GraphQL course by subscribing at