What is a Subscription

A subscription in GraphQL is a real-time operation. Unlike queries (one request, one response) and mutations (one request, one response), a subscription opens a persistent connection and the server pushes data whenever a relevant event occurs.

How it works

The client subscribes to an event type:

subscription {
  postCreated {
    id
    title
    author { name }
  }
}

The transport is typically WebSockets or Server-Sent Events. When a new post is created (triggered by a mutation), the server pushes the post data to all subscribed clients in the shape they requested.

Why it matters

Subscriptions make GraphQL a complete real-time API. Instead of polling the server for changes, the client is notified immediately. This is essential for chat applications, live dashboards, collaborative editing, and any feature that requires instant updates.

See How GraphQL Works for how subscriptions integrate with queries and mutations.