Query subscriptions

OpenReader supports GraphQL subscriptions via live queries. To use these, a client opens a websocket connection to the server and sends a subscription query there. The query body is then repeatedly executed (every 5 seconds by default) and the results are sent to the client whenever they change.

To enable subscriptions, add the additional --subscriptions flag to the squid-graphql-server startup command. The poll interval is configured with the --subscription-poll-interval flag. For details and a full list of available options, run

npx squid-graphql-server --help

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 Note that despite being deprecated from the regular query set, ${EntityName}s queries will continue to be available for subscriptions going forward.

Local runs

To enable subscriptions, add the --subscriptions flag to serve and serve:prod commands at commands.json:

commands.json

...
  "serve": {
    "description": "Start the GraphQL API server",
    "cmd": ["squid-graphql-server", "--subscriptions"]
  },
  "serve:prod": {
    "description": "Start the GraphQL API server in prod",
    "cmd": ["squid-graphql-server", "--subscriptions", "--dumb-cache", "in-memory"]
  },
...

A ws endpoint will be available the usual localhost:<GQL_PORT>/graphql URL.

Subsquid Cloud deployments

For Subsquid Cloud deployments, make sure to use the updated serve:prod command in the deployment manifest:

squid.yaml

# ...
deploy:
  # other services ...
  api:
    cmd: [ "sqd", "serve:prod" ]

The subscription wss endpoint will be available at the canonical API endpoint wss://{org}.subsquid.io/{name}/v/v{version}/graphql.

Example

Let's take the following simple schema with account and transfer entities:

type Account @entity {
  "Account address"
  id: ID!
  transfersTo: [Transfer!] @derivedFrom(field: "to")
  transfersFrom: [Transfer!] @derivedFrom(field: "from")
}

type Transfer @entity {
  id: ID!
  timestamp: DateTime! @index
  from: Account!
  to: Account!
  amount: BigInt! @index
}

After modifying commands.json start the GraphQL server with subscriptions with

npx squid-graphql-server

The following sample script will subscribe to the most recent transfers (by timestamp).

const WebSocket = require('ws')
const { createClient } = require('graphql-ws');

const port = process.env.GQL_PORT || 4350
const host = process.env.GQL_HOST || 'localhost'
const proto = process.env.GQL_PROTO || 'ws'


const client = createClient({
  webSocketImpl: WebSocket,
  url: `${proto}://${host}:${port}/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!');
    },
  }
);