APIer/09 · The three operations
CHAPTER 09 · Query, mutation, subscription

Queries, mutations and subscriptions

GraphQL defines three operation types and no others. A query reads data. A mutation writes data. A subscription receives events that the server sends over time.

§01

The query toolbox

Chapter 07 showed the simplest possible query. This section adds the five tools that appear in almost every real query: field arguments, aliases, fragments, variables, and directives.

TOOL 1

Field arguments: not only on the top-level field

An argument is a value you pass to a field, written in parentheses after the field name. A field accepts arguments only if the schema declares them — and the schema can declare arguments on a field at any depth, not just on the fields at the top of the query. Here comments takes an argument three levels in.

An argument on a nested field
1{
2 post(id: "1") {
3 title
4 comments(first: 3) {
5 body
6 }
7 }
8}
TOOL 2

Aliases: request the same field twice

Each key in the response is the field name by default. So what happens when you need the same field twice with different arguments? Both results would want the key post. An alias renames the key: write the name you want, a colon, then the field. The response then has one key per alias, and its shape is unambiguous.

query · two posts at once
1{
2 latest: post(id: "42") { title }
3 pinned: post(id: "1") { title }
4}
response · one key per alias
1{
2 "data": {
3 "latest": { "title": "Meeting GraphQL" },
4 "pinned": { "title": "Community guidelines" }
5 }
6}
TOOL 3

Fragments: a named selection set you can reuse

A selection set is the group of fields inside a pair of braces. A fragment gives one selection set a name so you can reuse it instead of repeating it. The list page, the detail page, and the search page all need the same post fields — write them once, then spread the fragment with ... wherever they are needed.

fragment · define once, spread anywhere
1fragment postFields on Post {
2 id
3 title
4 createdAt
5}
6
7{
8 feed: posts(first: 10) { ...postFields }
9 pinned: post(id: "1") { ...postFields }
10}
on Post is the type condition: this selection set may only be spread where a Post is being selected. Spread it somewhere else and validation rejects the document before execution starts. When the product team asks for a view count on every post card, you edit the fragment once.

Inline fragments: selecting fields that only some types have

A field can return an interface or a union — a type that stands for several concrete types. On such a field you may only select the fields that all of those types share. To reach the fields of one specific type, open an inline fragment: a type condition with no name.

... on <Type>
1{
2 search(term: "ada") {
3 __typename
4 ... on User {
5 name
6 }
7 ... on Post {
8 title
9 }
10 }
11}
__typename is a built-in field you can select in any selection set on an object, interface, or union type. It returns the name of the type that was actually returned, so the client knows which branch it is holding. Client caches also use it: they store each object once under a key built from its __typename and its id.
TOOL 4

Variables: how dynamic values enter a query

Which post the user opens is only known at run time. The first idea is usually to build the query text with string concatenation. Do not do that. It has the same problem as building SQL by concatenation: once user input is part of the query text, it is no longer data. It can change the structure of the query.

Wrong: string concatenation
1// User input goes straight into the query text
2const q = `{ post(id: "${input}") { title } }`;
3
4// Someone enters this, and the query is rewritten:
5// 1") { title } author { email } #
Right: variables
1// The query text never changes.
2// Dynamic values travel as a separate JSON object.
3const q = `query GetPost($id: ID!) {
4 post(id: $id) { title }
5}`;
6
7fetch("/graphql", {
8 method: "POST",
9 headers: { "Content-Type": "application/json" },
10 body: JSON.stringify({
11 query: q,
12 variables: { id: input },
13 }),
14});

What the extra typing buys you

Variables are declared on the operation — query GetPost($id: ID!) — and their values are sent as a separate JSON object next to the query. Three things follow. First, a value stays a value: it is never parsed as part of the query, so concatenation cannot be used to inject structure. Second, the server checks the declared type before it executes anything, so $id: ID! means a missing or wrongly typed id is rejected up front. Third, the query text is constant, so the server can parse and validate it once and cache the result, and persisted queries become possible: the client sends an identifier instead of the text (chapter 10).

TOOL 5

Directives: @include and @skip

The mobile layout does not show comments; the desktop layout does. You do not need two query documents for that. A directive attaches to a field and changes how it is handled — here, whether it is part of the request at all.

An executable directive
1query PostPage($id: ID!, $withComments: Boolean!) {
2 post(id: $id) {
3 title
4 comments(first: 3) @include(if: $withComments) {
5 body
6 }
7 }
8}
@include(if:) keeps the field only when the condition is true. @skip(if:) is the mirror image: it removes the field when the condition is true. If a field carries both, it is included only when @include is true and @skip is false.

Two are guaranteed; the rest are not

@include and @skip are the two executable directives that the specification requires every server to support. You can rely on them anywhere. @deprecated is different: it is a schema directive. It marks a field as outdated inside the schema definition, and you cannot write it in a query. A server may also define its own directives, but those work only on that server. Check the schema before using one.

All five tools appear in the query below. Click any line to see which part it is and what it does.

All five tools · click any line
}
}
}
}
}
Operation type · name · variables
query PostPage($id: ID!, $withComments: Boolean!) {

Three things on one line. query says this operation reads. PostPage is the operation name, which is what errors, logs, and monitoring will show. The parentheses hold the variable declarations: $id must be an ID and cannot be omitted (that is the !), and $withComments is a boolean. The values are not written here — they travel with the request as a separate JSON object.

§02

Mutations: changing data

Publishing a post, deleting a comment, adding a like — every write goes through a mutation. The syntax is almost the same as a query. Two rules are different.

The first rule is a convention: reads use query, writes use mutation. Nothing in the syntax stops you from changing data inside a query, but doing so misleads every person and every tool that reads your API. Complex input is usually collected into a single input type (chapter 08) instead of a long list of separate arguments.

The mutation
1mutation NewPost($input: CreatePostInput!) {
2 createPost(input: $input) {
3 id
4 title
5 createdAt
6 author { name }
7 }
8}
variables
1{
2 "input": {
3 "title": "My first post",
4 "body": "Notes from my first week with GraphQL."
5 }
6}
response · the new state
1{
2 "data": {
3 "createPost": {
4 "id": "42",
5 "title": "My first post",
6 "createdAt": "2026-07-20T09:30:00Z",
7 "author": { "name": "Ada Wong" }
8 }
9 }
10}
A mutation has a selection set too: the braces after createPost choose what you want to see once the write is done. The usual practice is to return the new state — the id of the new post, the createdAt the server generated — so the client can update its local cache without sending a second query.

The specification: top-level mutation fields execute in series

In a query, the top-level fields may be executed in parallel. Reads do not affect each other, so the order does not change the result. In a mutation, the specification requires the top-level fields to execute one after another, in the order they are written. The first one finishes before the second one starts.

Order is a guarantee
1mutation Transfer {
2 withdraw(from: "A", amount: 100) { balance } # runs first, to completion
3 deposit(to: "B", amount: 100) { balance } # only then does this start
4}

Why the difference? Writes can depend on each other. If "take money out" and "put money in" ran at the same time, the result would depend on timing. Serial execution removes that.

One detail people get wrong: this rule covers only the top-level fields of the mutation. Inside the payload of one mutation field — id, title, author above — the fields resolve like any query, and may run in parallel. And serial execution is not a transaction. If the second mutation fails, the first one is not undone. Rolling back is your server's job.

§03

Subscriptions: receiving events over time

A query and a mutation both follow one pattern: you ask once, the server answers once. A subscription is different. You register interest once, and the server sends results whenever the event happens.

subscription · send me each new comment
1subscription OnNewComment($postId: ID!) {
2 newComment(postId: $postId) {
3 body
4 author { name }
5 }
6}
The shape is the same as a query; the meaning is not. This is not "give me this now", it is "send me this every time it happens". One subscription, many results. The specification adds one restriction: a subscription operation must have exactly one root field. One subscription follows one kind of event.

A single request-and-response exchange cannot deliver something that happens ten minutes later, because it is already finished. A subscription therefore needs a connection that stays open. The usual transport is a WebSocket: a connection, opened from the browser, that both sides can send messages on until one of them closes it. SSE (Server-Sent Events) is also used: that one is still HTTP, but the response body stays open and the server keeps writing events into it, one direction only.

The life of one subscription, frame by frame
🖥️Client
Opening…
🗄️Server
The client sends subscription { newComment(postId: "1") … } and negotiates a connection that will stay open, usually a WebSocket. The subscription is registered on the server.
1 / 5
Worth a subscription
Frequent events, and delay is visible

Chat messages, the cursors of other people in a shared document, market prices, live scores. One second late is already noticeable. Polling for these is either too frequent (wasted server work) or too slow (visible lag).

Polling is enough
Slow changes, and delay does not matter

A notification badge, or a dashboard that nobody minds seeing a few minutes late. Sending a query on a timer is simpler and more reliable. An open connection costs memory, heartbeat messages, and reconnection handling on both sides.

§04

Errors: { data, errors } and partial results

This is where GraphQL differs most from REST. REST reports failure with a status code. GraphQL puts errors inside the response body, next to the data.

The specification fixes the shape of the response: a data entry and an errors entry, and both may be present at once. Each field is produced by its own resolver. When one resolver fails, the others keep running: the failed field is recorded in errors, and the fields that succeeded are still in data. This is called a partial result, and REST has no equivalent — there, one request either succeeds or fails. Click through the response below line by line.

A partial result · click any line
{
}
},
{
}
]
}
✕ Failure
"comments": null

The failure: the resolver for comments threw an error, for example because the comment service timed out. The field is set to null. The reason is not stored here — it is in the errors array below.

Partial results have one limit: non-null fields. Before the limit makes sense, you need to read the type notation correctly.

Reading non-null and list types
1type Post {
2 subtitle: String # may be null
3 title: String! # never null
4 tags: [String!]! # list is never null, and no item is null
5 notes: [String!] # list may be null; if present, no item is null
6 scores: [Int]! # list is never null; an item may be null
7}
The rule: ! applies to the thing immediately on its left. In [String!]! the inner ! belongs to String, and the outer one belongs to the list. Read from the inside out and the two are never confused.

A ! is a promise to the client: this position will never hold null. When a resolver for a non-null field fails, the server cannot keep that promise and cannot put null there either. So the null moves up to the nearest parent field that is allowed to be null, and everything below that parent is discarded with it. The same rule was stated in chapter 07; here is what it looks like step by step.

A non-null field fails: where the null goes
post
title
"Meeting GraphQL"
author
resolver threw 💥
author: User! # non-null
"post": { "title": "…", "author": ? }
Half way through execution, the resolver for author throws an error — say the user service is down. title is already resolved. The question is what to put in the author position.
1 / 4

res.ok cannot tell you whether a GraphQL request succeeded

A GraphQL server traditionally answers 200 OK even when every field failed. The status code describes the HTTP exchange; the errors are in the body. So the res.ok check from chapter 02 is not enough here. Read body.errors.

Calling a GraphQL API correctly
1const res = await fetch("/graphql", {
2 method: "POST",
3 headers: { "Content-Type": "application/json" },
4 body: JSON.stringify({ query, variables }),
5});
6const body = await res.json();
7
8// res.ok === true does not mean the query worked.
9if (body.errors) {
10 console.error("Some fields failed:", body.errors);
11}
12render(body.data); // data may still hold usable fields

The always-200 habit is changing. The GraphQL over HTTP specification is still a draft, and it allows a non-2xx status for errors that concern the whole request, such as a document that fails validation. Chapter 10 goes into it.

§05

Pagination: Relay cursor connections

A list cannot be returned all at once. Chapter 05 answered this for REST. The GraphQL world has a widely copied convention that looks unusual at first and solves the same problem.

The connections convention
1query Feed($cursor: String) {
2 posts(first: 10, after: $cursor) {
3 edges {
4 node { title }
5 cursor
6 }
7 pageInfo {
8 hasNextPage
9 endCursor
10 }
11 }
12}

Three levels for a list looks like a lot. Each one has a purpose. edges is the list of connections between the parent and each item: the item itself is under node, and anything that describes the relationship sits next to it — every edge carries its own cursor, and a schema can add fields such as the date a user started following. cursor is an opaque bookmark. It looks like nonsense on purpose: it may encode a sort key or a shard position, and the server does not want clients depending on that. Do not parse it; send it back unchanged. pageInfo describes the page itself: whether there is more, and where the next page starts.

Relay-style cursor pagination, one page at a time
posts(first: 3)
P1
P2
P3
P4
P5
P6
P7
P8
pageInfo { hasNextPage: true, endCursor: "c3" }
The first page: first: 3 and no after, so the server starts at the beginning. It returns P1–P3. pageInfo reports that more items exist (hasNextPage: true) and that the bookmark for the last item on this page is "c3".
1 / 4

A convention, not syntax

Connections come from the Relay specification (Relay is Meta's GraphQL client). The GitHub GraphQL API follows it, and you will meet it in many large schemas — but it is not part of the GraphQL language. The Rick and Morty API uses plain page numbers instead: characters(page: 2), with an info.next field holding the next page number. Both are in use. Cursors handle deep lists that change while you read them, without skipping or repeating items; page numbers are simpler and let a user jump straight to page 5. The practice tasks use the page-number style.

§06

Practice

GraphiQL is already set up for you; open it in the browser. Three tasks cover variables, fragments, aliases, and pagination.

§07

Quiz

Eight questions. The two about partial results and non-null bubbling matter most — if you miss them, read §04 again.

QUESTION 01 / 8

You are building a chat app. ① When a user enters a room, load the last 50 messages. ② The user sends a new message. ③ When someone else sends a message, it appears immediately. Which operation type fits each step?

QUESTION 02 / 8

What problem does an alias solve?

QUESTION 03 / 8

Compared with building the query text by concatenation (`{ post(id: "${input}") }`), what does using a variable ($id: ID!) give you?

QUESTION 04 / 8

The specification requires the top-level fields of a mutation to execute in series, while the top-level fields of a query may execute in parallel. Why the difference?

QUESTION 05 / 8

Can data and errors appear in the same GraphQL response?

QUESTION 06 / 8

The schema declares author: User! (non-null), and post itself is nullable. At run time the resolver for author throws. What does the response look like?

QUESTION 07 / 8

To fetch the next page with Relay-style connections, which two pageInfo fields do you need? (Select all that apply)

QUESTION 08 / 8

A subscription lets the server send events to the client at any time. What is normally used underneath to make that possible?

What to take away from this chapter
  • Three operation types, and no others: query reads, mutation writes, subscription receives events over time. Keeping reads and writes on the right operation is a convention, and other people rely on it.
  • The toolbox: the schema may declare arguments on a field at any depth; an alias renames a response key so the same field can be requested twice; a fragment names a selection set so it is written once; an inline fragment (... on Dog) reaches the fields of one type behind an interface or union.
  • Variables are declared on the operation and sent as a separate JSON object. The query text stays constant, which prevents injection through string building, lets the server check types before execution, and makes cached parsed documents and persisted queries possible. @include(if:) and @skip(if:) are the two executable directives every server must support.
  • A mutation returns the new state so the client can update its cache. Its top-level fields execute in series, in written order; the fields inside each payload resolve like a query. Serial execution is not a transaction.
  • The response is always { data, errors }, and both may appear together — a partial result. A failing non-null field cannot hold null, so the null moves up to the nearest parent that allows it. Read ! as applying to the thing on its left.
  • A GraphQL server traditionally answers 200 OK even on failure, so res.ok proves nothing. Check body.errors.
  • For Relay pagination, watch two fields: hasNextPage decides whether to continue, and endCursor goes into the next request as after. A cursor is an opaque bookmark — do not parse it.