Skip to content logo

Illustrated Notes

Speaking the GraphQL Query Language

Published or updated on July 30, 2019

Small GraphQL schema dictionary illustration

GraphQL is undoubtably one of the popular kids on the webdev playground this year (alongside Svelte and React Hooks).

If you haven't heard of GraphQL, the TLDR is that it's a new way to request data from an API.


One that's easier, faster, better, and stronger than the old RESTful API system.

(There's more to it than that, but it gets complex so I'm in the middle drawing a whole WTF is GraphQL explainer for you – stay tuned)

If you're lucky enough to already grok GraphQL, you'll know the QL stands for Query Language – aka. the language we talk to our GraphQL API in.

It's not a terribly complex language, but you'll still need to do some syntax studying to get the hang of it.

Thankfully the magnificent Eve Porcello just released a new course on egghead that runs you through the full GraphQL vocabulary.

Course illustration of a set of dictionary books with the word 'schema' across them

It's a wonderful introduction for anyone new to the GraphQL ecosystem – Eve explains all the parts of the playground interface that are not in the least bit intuitive. I'd been stumbling about in my own GraphQL queries lost and afraid until I worked through this.

Anyways, as usual I drew some things:

How to talk to a GraphQL API. We can use the graphQL playground to send queries to a GraphQL endpoint. The playground lets us explore our data before making any requests

A query is a request for data. We open it with the query keyword and a set of curly braces. Curly braces wrap around a selection and say "go look inside this object." Blank spaces at the end of a line are fields that say "I want his data please." We can also add the 'total' and 'all' keywords in front of any list of objects.

Inside the playground, ctrl + space is a magic combination that reveals all the available fields of a query

We can filter our data by adding arguments to our queries. This means we only get the data we want. We can also use mutations to change the data. This includes creating, updating, and deleting data.

Bonus poster!

This is the first set of illustrated notes we're turning into an IRL atoms-and-quarks poster on egghead's swag store.

a framed graphql illustrated print

a close-up image of one section of the print

There's framed versions and unframed, depending on how fancy you feel. You can buy one here if you so desire!

(thanks to everyone who nagged me on twitter to finally sort that out)

The Whole Illustrated Note

The full GraphQL query language illustrated note

Want to learn more?

A high-res & printable version of the notes, plus the full course is avaliable here on the GraphQL Query Language page.