A Beginner’s Dive into GraphQL — Part 2 — GraphQL Schema, Field, Arguments, Aliases, and Fragments

GraphQL Schema

In Beginner’s Dive into GraphQL — Part 1, we discussed what is GraphQL and things we can do with it.

To continue our journey further with GraphQL, we will dive into GraphQL Schema, Operations, Fields, Arguments, Aliases, and Fragments.

What is GraphQL Schema?

The starting point to any GraphQL stack is defining the schema. A GraphQL schema is just about defining how the data available to the client is related and what queries can be made to retrieve it. Additionally, it describes the mutations available and the data they can return.

A schema is constructed of a set of object types — which are maps of named fields, each of which is another type, either another object or a scalar base type. In simple language, object types are the nodes in the type system’s “graph” and the scalar types are leaves.

It’s useful to remember how a GraphQL query works: it starts at a given operation, and walks a (tree-like) path through the type system, choosing one or more fields from each object type that it encounters.

Types of Operations

There are three kinds of operation available at the entry points to the schema:

• Schema must have query object type whose fields are the set of query endpoints of the server application.
• A schema may optionally have mutation object type, whose fields are the set of mutations available on the server.
• The schema may have a subscription object type, whose fields are the set of subscriptions.

An example of the schema with at least one of all three kinds of operation:

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

In this example, the three object types Query, Mutation, and Subscription would be defined elsewhere. The names of those types can be anything, but it’s common practice to pick the names above.

What is Field?

As we discussed earlier, GraphQL is a simple query language for requesting information from specific fields on objects. Let’s look at the simple example:

{
  author{
    name
  }
}

The response you get from the server may look like this:

{
 “data”: {
  “author”: {
   “name”: “Krish Williams”
  }
 }
}

You can see immediately that the query has exactly the same shape as the result. The field name returns a String type, in this case, the name of the author. (For the example purpose here, we are assuming that this server has all of the information for only one author)

As we discussed in our first post, GraphQL queries can traverse related objects and their fields, letting clients fetch lots of related data in one request, instead of making several roundtrips as one would need in a classic REST architecture. In the previous example, we just asked for the name of the author which returned a String, but fields can also refer to Objects. In that case, you can make a sub-selection of fields for that object. Let’s see following the example of that.

{
  author{
    name,
    books{
       title
    }  
  }
}

Response you get from the server may look like this:

{
 “data”: {
  “author”: {
   “name”: “Krish Williams”,
   “books”: [
        {
         “title”: “GraphQL - No REST Architect”
        },
        {
        “title”: “JavaScript - Inside Out”
        }
     ]
   }
 }
}

GraphQL queries look the same for both single items or lists of items, however we know which one to expect based on what is indicated in the schema.

What are Arguments?

Just like any other normal query language, GraphQL allows us to pass the arguments on fields. But in REST architecture, you can pass a single set of arguments on only root element whereas, in GraphQL, every field and the nested object can get its own set of arguments, provided GraphQL server schema allows it.

Example of an argument on a root element:

{
  author(name: "Krish Williams") {
    age
  }
}

Example of an argument on a sub-field:

{
  author(name: "Krish Williams") {
    age,
    books(title: "GraphQL - No REST Architect") {
       publishedIn
    }
  }
}

Aliases

One of the flexibility that GraphQL gives us is aliases — they let you rename the result of a field to anything you want.

{
  krishWilliams: author(name: "Krish Williams") {
    age
  }
  mattAtkins: author(name: "Matt Atkins") {
    age
  }
}

In the above example, the two author fields would have conflicted, but since we can alias them to different names, we can get both results in one request.

{
 “data”: {
  “krishWilliams”: {
   “age”: 35
  }
  “mattAtkins”: {
   “age”: 42
  }
 }
}

What is Fragments?

The billionaire software magnate Bill Gates said:

I will always choose a lazy person to do a difficult job because a lazy person will find an easy way to do it.

After reading this line, I could conclude that being a developer we have a right to be lazy. After all, that will push us to write codes which can do repetitive task easily. That’s what Fragments does for us in GraphQL. GraphQL’s reusable units called fragments. Imagine, we are the biggest book-worms. But we are confused which author should be next in our list and we want to compare both of them side by side along with their books. You can imagine that such a query could quickly get complicated because we would need to repeat the fields at least twice — one for each side of the comparison.

Fragments let you construct sets of fields, and then include them in queries where you need to. Here’s an example of how you could solve the above situation using fragments:

{
  leftComparison: author(name: "Krish Williams") {
  ...comparisonFields
  }
  rightComparison: author(name: name: "Matt Atkins") {
  ...comparisonFields
 }
}
fragment comparisonFields on Author{
  age,
  books {
    title,
    rating
  }
}

And response you receive from the server may look like this:

{
  "data": {
    "leftComparison": {
      "age": 35,
      "books": [
        {
          "title": “GraphQL - No REST Architect”,
          "rating": "4.5 stars"
         },
         {
          "title": “JavaScript - Inside Out”,
          "rating": "4 stars"
         }
      ]
   },
"rightComparison": {
      "age": 42,
      "books": [
        {
          "title": “GraphQL - REST replacement”,
          "rating": "3.7 stars"
         },
         {
          "title": “JavaScript - All You Need”,
          "rating": "5 stars"
         }
       ]
     }
  }
}

The above query would be pretty repetitive if the fields were repeated for both of the authors. The concept of fragments is frequently used to split complicated application data requirements into smaller chunks, especially when you need to combine lots of UI components with different fragments into one initial data fetch.

We will uncover more about GraphQL such as Variables, Directives, Inline Fragments, Mutations, data types in next few weeks. Any suggestion or question on this article, please feel free to write me at hima.chhag@gmail.com or in the comment section below.

Happy Coding!

• A Beginner’s Dive into GraphQL — Part 1
• A Beginner’s Dive into GraphQL — Part 3