GraphQL Operations
GraphQL defines three operation types. Every request to a GraphQL API is one of these. The operation type determines whether the request reads data, writes data, or establishes a real-time event stream.
3
Operations
Spec reference: Operation types are defined in §2.3 of the GraphQL specification. spec.graphql.org/October2021 §2.3 →
Query
A GraphQL query is a read-only fetch operation. The server must not modify any data when executing a query. Queries are side-effect free and may be cached. Multiple queries can be sent in a single document; the optional operationName field selects which one to execute. Queries may be anonymous (omit the query keyword) but named queries are strongly recommended for debugging and APM tooling.
query OperationName($var: Type) { field(arg: $var) { subField } }
Mutation
A GraphQL mutation is a write operation that modifies server-side data. Mutations execute serially – if a document contains multiple mutation fields, they run one after another in declaration order, not in parallel. This guarantees that a mutation that increments a counter followed by a mutation that reads it sees the updated value. Mutations return data just like queries – clients specify the fields they want back in the response.
mutation OperationName($input: InputType!) { mutationField(input: $input) { id field } }
Subscription
A GraphQL subscription establishes a long-lived connection over which the server pushes events to the client as they occur. Subscriptions are executed once per event – when a subscribed event fires, the server runs the subscription selection set against the event payload and pushes the result. The dominant transport is WebSocket using the graphql-ws protocol (RFC: github.com/enisdenjo/graphql-ws). Server-Sent Events (SSE) is also used for unidirectional push.
subscription OperationName($var: Type) { eventField(filter: $var) { id payload } }
Quick Comparison
| Operation | Purpose | Transport | Side effects |
|---|---|---|---|
| query | Read data | HTTP POST (or GET) | None – spec-guaranteed |
| mutation | Write data | HTTP POST | Yes – serial execution |
| subscription | Real-time events | WebSocket / SSE | None – event listener |