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!');
    },
  }
);