In addition to fetching data using queries and modifying data using mutations, the GraphQL spec supports a third operation type, called
GraphQL subscriptions are a way to push data from the server to the clients that choose to listen to real time messages from the server. Subscriptions are similar to queries in that they specify a set of fields to be delivered to the client, but instead of immediately returning a single answer, a result is sent every time a particular event happens on the server.
A common use case for subscriptions is notifying the client side about particular events, for example the creation of a new object, updated fields and so on.
GraphQL subscriptions have to be defined in the schema, just like queries and mutations:
On the client, subscription queries look just like any other kind of operation:
The response sent to the client looks as follows:
In the above example, the server is written to send a new result every time a comment is added on GitHunt for a specific repository. Note that the code above only defines the GraphQL subscription in the schema. Read setting up subscriptions on the client and setting up GraphQL subscriptions for the server to learn how to add subscriptions to your app.
In most cases, intermittent polling or manual refetching are actually the best way to keep your client up to date. So when is a subscription the best option? Subscriptions are especially useful if:
- The initial state is large, but the incremental change sets are small. The starting state can be fetched with a query and subsequently updated through a subscription.
- You care about low-latency updates in the case of specific events, for example in the case of a chat application where users expect to receive new messages in a matter of seconds.
A future version of Apollo or GraphQL might include support for live queries, which would be a low-latency way to replace polling, but at this point general live queries in GraphQL are not yet possible outside of some relatively experimental setups.
Because subscriptions maintain a persistent connection, they can't use the default HTTP transport that Apollo Client uses for queries and mutations. Instead, Apollo Client subscriptions most commonly communicate over WebSocket, via the community-maintained
Let's look at how to add support for this transport to Apollo Client.
Now, queries and mutations will go over HTTP as normal, but subscriptions will be done over the websocket transport.
With GraphQL subscriptions your client will be alerted on push from the server and you should choose the pattern that fits your application the most:
- Use it as a notification and run any logic you want when it fires, for example alerting the user or refetching data
- Use the data sent along with the notification and merge it directly into the store (existing queries are automatically notified)
subscribe, you can easily do the latter.
subscribe is a method available directly in
Apollo service. It works like
watchQuery but it's for GraphQL Subscriptions.
In the example above, the
CommentsComponent subscribes to
commentAdded events and just like in
watchQuery gets receives every emitted result.
subscribeToMore is a bit different than
subscribe. It is a method available on every watched query in
apollo-angular. It works just like
fetchMore, except that the update function gets called every time the subscription returns, instead of only once.
Here is a regular query:
Now, let's add the subscription.
Add a function called
subscribeToNewComments that will subscribe using
subscribeToMore and update the query's store with the new data using
Note that the
updateQuery callback must return an object of the same shape as the initial query data, otherwise the new data won't be merged. Here the new comment is pushed in the
comments list of the
and start the actual subscription by calling the
subscribeToNewComments function with the subscription variables:
subscribelistens to results emitted by a GraphQL Subscription and lets you update one or many queries.
subscribeToMorelistens to GraphQL Subscription as well but is tightly connected with one query.
We recommend to use
subscribe in most cases and leave
subscribeToMore for things like pagination.
In many cases it is necessary to authenticate clients before allowing them to receive subscription results. To do this, the
SubscriptionClient constructor accepts a
connectionParams field, which passes a custom object that the server can use to validate the connection before setting up any subscriptions.
You can use
connectionParamsfor anything else you might need, not only authentication, and check its payload on the server side with SubscriptionsServer.