Skip to main content
Version: Firesquid

Query subscriptions

Available since @subsquid/graphql-server@2.0.0

info

This is an experimental feature. Reach out on Squid Devs Chat for more details.

The OpenReader supports GraphQL subscriptions via live queries. The query is repeatedly executed (every 5 seconds by default) and the clients are responsible for handling the result set updates.

To enable subscriptions, add the additional --subscriptions flag to the squid-graphql-server startup command. For Aquarium deployments, update the api command in the deployment manifest:

squid.yaml
# ...
deploy:
# other services ...
api:
cmd: [ "npx", "squid-graphql-server", "--subscriptions" ]

For local development, update accordingly the Makefile and the scripts in package.json:

Makefile
...
serve:
@npx squid-graphql-server --subscriptions
...

The subscriptions will be available at the standard squid endpoint but with the wss:// protocol.

For each entity types, the following queries are supported for subscriptions:

  • ${EntityName}ById -- query a single entity
  • ${EntityName}s -- query multiple entities with a where filter

Example

The squid-substrate-template has a sample script to demonstrate how to subscribe to the five most recent transfers on Kusama:

const client = createClient({
webSocketImpl: WebSocket,
url: `ws://localhost:4350/graphql`,
});

client.subscribe(
{
query: `
subscription {
transfers(limit: 5, orderBy: timestamp_DESC) {
amount
blockNumber
from {
id
}
to {
id
}
}
}
`,
},
{
next: (data) => {
console.log(`New transfers: ${JSON.stringify(data)}`);
},
error: (error) => {
console.error('error', error);
},
complete: () => {
console.log('done!');
},
}
);