Table of contents

  • What is GraphQL?Challenges with dataThe power of a precise requestTypes and fields
  • The Query
  • Types
  • Schema
  • Interfaces & Unions
  • Arguments
  • Mutations

What is GraphOS?The GraphQL developer platform

What is GraphQL?

Calling all humans! Because GraphQL is meant for you, too.

But, what is GraphQL? That's the question a lot of us have been asking - and finding a human-friendly answer is sometimes the hardest part!

Whether you're just beginning your GraphQL journey or working to build a sturdier foundation, we're delighted to make the introductions. Our goal is to make learning GraphQL easier than ever before. For you, that means more time playing with the concepts, and less time wrestling with the jargon!

Ready to jump in? We'll start by talking about the way we request data, and how GraphQL uses types and fields to transform the process. Let curiosity lead the way!

Challenges with data

If there's one thing GraphQL excels at, it's working with data. And the amount of data we have at our fingertips is increasing all the time! We can say the same about the number of places we store data. We have servers, databases, even entire companies that are responsible for housing and preserving data. We've come a long way since the days of filing cabinets and storage boxes, and data's ability to drive discoveries, reveal insights, and help us innovate has only become more powerful.

The big question, then, is how do we get our hands on this data? And just as importantly, how do we handle getting data from lots of different places? Whether we're observing trends or asking specific questions, we need a consistent, structured way to tackle the challenge of fetching, organizing, and working with our data.

GraphQL, which stands for Graph Query Language, is a technology that developers all over the world are adopting to simplify this task. One of its biggest advantages over similar solutions is the power it gives us to ask for exactly what we need in a single request.

The power of a precise request

Let's unpack that by thinking about how we ask other people for information. If you ask someone what their name is, they probably don't respond with their name, their age, their hometown, and whether they have a dog. It'd be really irritating if every time you asked a question, you had to filter out a lot of unnecessary information that you didn't ask for. Instead of getting the definition of a single word, you'd have to take the whole dictionary! There'd be a lot more work on each of us to pick out the information we really care about from all the extra clutter.

Feels unintuitive, right? But this how a lot of data exchange over the internet works! Information about a thing is stored in a location that we can access using a specific link. We can send a request to the link to ask for a single detail, but often it sends back way more information than we need.

GraphQL lets us approach requests for data in a more natural way. When we have an understanding of what kinds of data are available to us, we can build a document called a schema. The schema lets us visualize, all at once, the different objects of data we have to work with in an application, and what attributes can be assigned to them. Then, using the schema, we can build our requests incrementally and naturally—including the specific things we want to know about, and forgetting the rest! The types and fields we put into our schema make this possible.

  What does a schema look like?

Types and fields

We use types in GraphQL to draw boundaries around particular kinds of data, and also to understand what kind of data we'll get back when we ask for something in particular. We might create a type, for example, called Human. The Human type could list its attributes, called fields. We've already seen a few examples of what these fields could possibly be: name, age, hometown, and even whether they have a dog.

A human figure in pink, accompanied by numerous properties belonging to a human, such as: name, age, hometown, and whether they have a dog. These could be fields on a Human type!

For each of these attributes of a Human type, we can specify in the schema the type of data we expect them to return. (A human being's name, for example, will probably consist of letters, not numbers or symbols!) Knowing ahead of time what kind of data we'll get back when we send a request makes it a lot easier to predict how to handle the results.

  What types can we use in GraphQL?

As a result of mapping our data to types and fields, the schema becomes our source of truth. We know what kinds of things there are, and the specific details we can ask about for each of them. But GraphQL lets us go a step further—we can put the "graph" in "GraphQL" to good use by representing the relationships that exist between types. A Human might be enrolled in a particular Course. The Course could be part of a Track, which belongs to a School.

An image demonstrating the connections between different types. A Human attends a Course, which is part of a Track, that is offered at a School.

By using these relationships, we can build a big web of data. Most importantly, we can write a single request that can travel from Human all the way to School and back again, gathering just the information we ask for—nothing more, and nothing less.

Imagine a request as specific as: "Give me the name of this Human; the schedule and class size for the Course they're enrolled in; the other courses in the same Track; and the year the track's School was founded."

GraphQL helps us overcome the requirement to make multiple follow-up requests for each new piece of data: we can write a single request and get all the information at once.

The schema that maps out these types and relationships is extremely powerful, but it's useless without a way to actually ask for that information. For that, we have something called the Query.

Up Next: The Query  

About is maintained by the Apollo team. Our goal is to give developers and technical leaders around the world all of the tools they need to understand and adopt GraphQL. 2023