Skip to main content
Version: ArrowSquid

Query subscriptions

Available since @subsquid/graphql-server@2.0.0

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 for local runs, add the --subscriptions flag to the serve command at commands.json:

"serve": {
"description": "Start the GraphQL API server",
"cmd": ["squid-graphql-server", "--subscriptions"]

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

Aquairum deployments

For Aquarium deployments, update the api command in the deployment manifest:

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

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


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 GraphQL server with subscriptions can be started with

sqd serve

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`,

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