GraphQL: A brief introduction into queries and mutations

You've probably heard of "queries" and "mutations" a bunch of times - in this article I'll go over the basics of what they are and how to use them.

In short

On a basic level, we can think of queries as doing the same thing as a GET request in a RESTful API. Mutations can be compared to methods like DELETE, PUT, and PATCH, or anything else that updates the data.

Queries

Queries are kinda like functions in JavaScript. They can be named or anonymous, take arguments or not take them, but they always return some sort of data.

{
  posts{
    title
    author
  }
}

You can think of a query as asking for a specific field on an object. We can't query the whole object, we have to query the fields it contains.

// won't work
{
  posts{
  }
}

GraphQL still recognises queries when they don't have a name or use the 'query' operation type. It's shorthand syntax, but it is better to specify the type of operation we make and give it a name. The operation type can be query, mutation, or subscription, and we have creative freedom in choosing a name for it.

It is best to choose a name that reflects what is happening (GetPosts to get all posts, UpdatePost to update posts etc.) and its conventional to use PascalCase when we name queries and mutations.

Arguments

Queries, like functions, can take arguments - in some cases they might even be required. If an argument (or field) is required, it'll have an exclamation mark after it and won't work if you try to query it without the parameter it requires.

query{
  postByID(id:3){
    title
  }
}

Variables

In the code snippet above, we're writing our arguments directly into our query string, but there will be times when we want our arguments to be dynamic, because we might not know in advance what the query criteria will be, e.g. give me all the posts with ___ as the author.

We can make this work by using variables. To use variables, our query has to have an operation type and a name.

query GetPostByID($id:Int!){
  postByID(id:$id){
    title
  }
}

We've given the query a name, declared the parameter it takes, and the type of that argument. We will have already declared that this query takes a parameter and the type of it in the Schema, so its good to check that whatever we're using here is the same as what we've already declared.

We can now replace the hard coded value in the query with $arg. This arg has to have the same name as the parameter. The $ doesn't do anything special, its just highlights the variable.

Using variables helps make your code more DRY and dynamic.

Default variables

We can provide default values by adding the default value after the type declaration.

query GetPostByID($id:Int!=2){
  postByID(id:$id){
    title
  }
}

If we do this, we can call the query without passing a variable. When we do pass a variable the default is overridden.

Mutations

We write mutations in the same way. We use the mutations operation type, pass in the data we want to mutate, and can use variables to make the mutation more dynamic.

Testing this out for yourself

If you want to mess around with basic queries and mutations yourself you can do so with this super basic demo app. Happy coding :)