subscribe in GraphQL: syntax, parameters and examples

GraphQL · Function

GraphQL subscriptions are long-lived operations that deliver selected data when relevant events occur. They use a schema’s Subscription root type and an implementation-selected transport.

How it works

A GraphQL subscription is a long-lived operation that receives selected data whenever relevant server-side events occur. The client sends a subscription operation, while the server commonly connects its resolver to a pub/sub system and chooses a transport such as WebSockets or server-sent events.

Syntax

subscription OperationName {
  rootField {
    selectedField
  }
}

Returns

A stream of selected GraphQL results corresponding to successive events.

Key points

Subscriptions let clients receive incremental updates through a request that remains active over time.
Subscription fields use the same general field-definition model as query and mutation fields.
The schema exposes subscription fields through the Subscription root operation type.
One GraphQL document can declare multiple subscription operations, each representing a different event stream.
Implementations commonly rely on pub/sub infrastructure to publish runtime events and feed subscription resolvers.
Common transports for carrying subscription traffic include WebSockets and server-sent events.

Common mistakes

A subscription operation may contain only one root field, even though a document can define multiple subscription operations.
The GraphQL operation alone does not determine the network transport; the server and client must agree on a supported protocol.
A schema without a subscription root type does not provide subscription support.

Example: Subscribe to review events

subscription NewReviewCreated {
  reviewCreated {
    rating
    commentary
  }
}

This operation asks the server to deliver selected review fields as matching events occur.

When to use it

Live activity feeds

Deliver newly created reviews, messages, or comments as they happen.

Real-time monitoring

Push state changes to dashboards without repeated polling.

Collaborative updates

Notify connected clients when shared application data changes.

Interview questions

QWhat is a GraphQL subscription?

A subscription is a long-lived GraphQL operation for receiving updates in response to events. Its result is delivered over time rather than as one finite response.

Follow-up: How are subscription events commonly produced? A separate pub/sub system publishes events, and subscription resolvers consume them.

QHow does a client define a subscription?

The client declares the subscription operation type and selects the fields it wants from the subscription root field. The server then delivers matching event data according to that selection.

Follow-up: What constraint applies to the root selection? Each individual subscription operation must have exactly one root field.

QWhich transport does GraphQL subscriptions use?

GraphQL leaves transport selection to the server. WebSockets and server-sent events are common implementations, and clients must support the selected protocol.

Follow-up: Does GraphQL itself require WebSockets? No; the protocol is outside the GraphQL specification and can be chosen by the implementation.

query
mutation
Subscription
WebSockets
server-sent events
pub/sub

Source: Subscriptions - GraphQL. Checked 2026-10-15.

subscribe