Overview
In this section, we'll cover:
- how to leverage Federated Subscriptions to enable real-time data use cases
- how to enrich real-time data via Federation
Prerequisites
- Our supergraph running in the cloud
Federated subscriptions
GraphQL subscriptions enable clients to receive continual, real-time updates whenever new data becomes available. Unlike queries and mutations, subscriptions are long-lasting. This means a client can receive multiple updates from a single subscription:
Subscriptions are best suited to apps that rely on frequently changing, time-sensitive data (examples include: incoming reviews, stock prices, IoT sensor readings, live chat, or sports scores).
Federated subscriptions: KBT Threads
At KBT threads we have new product reviews being posted almost every second. There is a desire to showcase the latest reviews in real time.
While this sounds straightforward, there are questions about enriching the real-time data to show human-readable products and the user information that left the review. To show the real-time review data we will leverage Federated Subscriptions.
How it works
We have already done the work to send a review event from our NoSQL database to our products subgraph whenever a review is added. A review event is triggered every time a new review is posted. This comes from our NoSQL database to our product subgraph in a JSON format.
An example of a review event looks like this:
{"id": 1,"body": "This was a great find! would highly recommend.","product": {"id": "143"},"user": {"id": "10"}}
For us to show relevant data about this review, we need to enrich this event with data from our products subgraph and our users subgraph.
We will do this by creating a federated subscription. This will enable us to return the review information in the event, such as the review body. It will also allow us to provide detailed information that was not included in the event, such as product name, product description, product images, user first name, and user last name.
✏️ 1. Open the products-schema.graphql
file: in GitHub, click the products-schema.graphql
file.
Click the ✏️ pencil edit button on the top-right of the page to begin editing the file.
✏️ 2. Add the Review
type.
In the GitHub text editor find the comment that says "#ADD REVIEW FIELDS AND RETURN TYPES HERE"
. It should be on line 142
. Add the fields and return types for the Review type. The review should include an id
, body
, the product
that was reviewed, and the user
that created that review.
Your Review
type should look like this:
type Review @key(fields: "id") {id: Int!body: String!product: Product!user: User!}
✏️ 3. Add the Subscription
type
Now that we have a review type in our schema, we can add a subscription that is triggered each time a review is added to our database.
In the GitHub text editor find the comment that says "#ADD SUBSCRIPTION FIELDS AND RETURN TYPES HERE"
. It should be on line 153
. Add the field and return type for the subscription. The subscription should include a field called reviewAdded
and should return a Review
type.
type Subscription {reviewAdded: Review}
✏️ 4. Commit changes
Click the Commit changes button in the upper right of the text editor.
Subscribing to live reviews
Now that we have added our subscription to the schema, it is time to see it come through in real time. Navigate to Explorer in GraphOS Studio by selecting your graph and clicking the Explorer on the left-hand side:
In Explorer, make a new Subscription request that retrieves the reviews. Include additional fields such as the name of the user who made the review, the product name, description, and price.
You can build this by selecting each field you want present in the subscription:
Alternatively, you can copy and paste this subscription into the Explorer window.
subscription ReviewSubscription {reviewAdded {idbodyproduct {nameshortDescriptionprice}user {firstNamelastName}}}
Now trigger the subscription by clicking the Review Subscription button in the upper middle of the page.
On the right-hand side, you should see live reviews coming into your explorer. You may have to expand the subscription window by clicking and dragging the bar up towards the top.
Up next
In this module, we've covered how Federated subscriptions allows us to enable real-time data use cases. In the next section, we will learn how to simplify and accelerate development by connecting REST APIs directly into a Supergraph with the power of Apollo Connectors.