Subscriptions in GraphQL

When a GraphQL schema declares

type Subscription {
    blog: BlogPost
}

a client can submit a subscription query (say over websocket for a persistent connection--such as graphql-ws):

subscription {
    blog {comments {body}}
}

and get new data when something changes. The exact "change event" is left as an exercise to the implementation, but in the above it would be when the list of comments changes (typically when a new comment gets added)

Subscriptions in StepZen

Any query in StepZen can be converted into a subscription. To give an example:

type Query {
    foo: Foo!
    @rest (endpoint: "...")
}
type Subscription {
    fooSub: Foo! @materializer (query:"foo")
}

That's it! foo can be a @rest query, a @dbquery query, a federated @graphql query, or an @sequence. Any way you construct your queries, each and everyone of them can be converted into a subscription!

Under the hood, StepZen does long polling to determine what has changed, and more mechanisms are coming, but you can start using it right now, and we will continue to optimize it.

A simple example using StepZen's Docker image

Currently, subscriptions work when you use StepZen's docker image. They will soon roll out the cloud, so do periodically check our Discord or blog for updates.

A simple example of subscriptions in StepZen is available in our example repo. Clone the repo:

git clone git@github.com:stepzen-dev/subscription-blog.git

and follow the instructions in README.md.

How it works

The subscription is against a REST backend: https://api.binance.us/api/v3/ticker?symbol=ETHBTC

StepZen does a long polling and pushes back to the client whenever a new value is found. You can check out the code in index.graphql to see what is going on, it should be fairly self-explanatory.

Because any Query field can be converted to a Subscription field, you can set up subscription against databases, GraphQL endpoints, or any combination thereof. Try them for yourself.

UPDATE December 6, 2022 Subscriptions are now available for the StepZen managed cloud service.