GraphQL Subscriptions (GQLS) are a mechanism which allow clients to subscribe to changes in a piece of data from the server, and get notified whenever that data changes.
A GraphQL Subscription looks very similar to a query, with the exception that it uses the subscription keyword:
- Subscribing to the above subscription will notify the client whenever the specified
Feedbackobject has been "liked" or "unliked". The
feedback_like_subscriptionfield is the subscription field itself, which takes specific input and will set up the subscription in the backend.
feedback_like_subscriptionreturns a specific GraphQL type which exposes the data we can query in the subscription payload; that is, whenever the client is notified, it will receive the subscription payload in the notification. In this case, we're querying for the Feedback object with its updated
like_count, which will allows us to show the like count in real time.
An example of a subscription payload received by the client could look like this:
In Relay, we can declare GraphQL subscriptions using the
graphql tag too:
- Note that subscriptions can also reference GraphQL variables in the same way queries or fragments do.
There are two ways of executing a subscription against the server. The
requestSubscription API and using hooks.
In order to execute a subscription against the server in Relay, we can use the
Let's distill what's happening here:
requestSubscriptiontakes an environment, the
graphqltagged subscription, and the variables to use.
- Note that the
inputfor the subscription can be Flow typed with the autogenerated type available from the
FeedbackLikeSubscription.graphqlmodule. In general, the Relay will generate Flow types for subscriptions at build time, with the following naming format:
requestSubscriptionalso takes an
onErrorcallbacks, which will respectively be called when the subscription is successfully established, or when an error occurs.
requestSubscriptionalso takes an
onNextcallback, which will be called whenever a subscription payload is received.
- When the subscription payload is received, i**f the objects in the subscription payload have IDs, the records in the local store will automatically be updated with the new field values from the payload**. In this case, it would automatically find the existing
Feedbackobject matching the given ID in the store, and update the values for the
- Note that any local data updates caused by the subscription will automatically cause components subscribed to the data to be notified of the change and re-render.
However, if the updates you wish to perform on the local data in response to the subscription are more complex than just updating the values of fields, like deleting or creating new records, or adding and removing items from a connection, you can provide an
updater function to
requestSubscription for full control over how to update the store:
Let's distill this example:
storeargument, which is an instance of a
RecordSourceSelectorProxy; this interface allows you to imperatively write and read data directly to and from the Relay store. This means that you have full control over how to update the store in response to the subscription payload: you can create entirely new records, or update or delete existing ones. The full API for reading and writing to the Relay store is available here: https://facebook.github.io/relay/docs/en/relay-store.html
- In our specific example, we're adding a new comment to our local store when we receive a subscription payload notifying us that a new comment has been created. Specifically, we're adding a new item to a connection; for more details on the specifics of how that works, check out our Updating Connections section.
- Note that the subscription payload is a root field record that can be read from the
store, specifically using the
store.getRootFieldAPI. In our case, we're reading the
comment_create_subcriberoot field, which is a root field in the subscription response.
- Note that any local data updates caused by the mutation
updaterwill automatically cause components subscribed to the data to be notified of the change and re-render.
You can also use hooks to subscribe to a subscription query.
This is only a thin wrapper around the
requestSubscription API. It's behavior:
- Subscribe when the component is mounted with the given config
- Unsubscribe when the component is unmounted
If you have the need to do something more complicated, such as imperatively requesting a subscription, please use the
requestSubscription API directly.
Is this page useful?