Advance Live Queries
Subscribing to Queries to Get Real-Time Alerts Whenever Data in the Query Result Set Changes.
Follow this guide for the standard Live Query implementation:

Advanced Connection

We manage a global WebSocket connection for you in our standard connection which is suitable for most cases. However, in some cases you have multiple LiveQuery servers and want to connect to all of them, a single WebSocket connection isn't enough. We've exposed the LiveQueryClient for such scenarios.

LiveQueryClient

A LiveQueryClient is a wrapper of a standard WebSocket client. We add several useful methods to help you connect/disconnect to LiveQueryServer and subscribe/unsubscribe a MoralisQuery easily.

Initialize

1
let Moralis = require('moralis');
2
let LiveQueryClient = Moralis.LiveQueryClient;
3
let client = new LiveQueryClient({
4
applicationId: '',
5
serverURL: '',
6
javascriptKey: '',
7
masterKey: ''
8
});
Copied!
  • applicationId (required): it's the applicationId of your Moralis Dapp.
  • serverURL (required): it's the URL of your LiveQuery server.
  • javascriptKey
  • masterKey
javascriptKey and masterKey are used for verifying the LiveQueryClient when it tries to connect to the LiveQuery server. If you set them, they should match your Moralis app. You can check the LiveQuery protocol here for more details.

Open

1
client.open();
Copied!
After you call this, the LiveQueryClient will try to send a connect request to the LiveQuery server.

Subscribe

1
let query = new Moralis.Query('Game');
2
let subscription = client.subscribe(query, sessionToken);
Copied!
  • query (required): it is the MoralisQuery you'll want to subscribe.
  • sessionToken: If you provide the sessionToken, the LiveQuery server will only send updates to clients whose sessionToken is fit for the MoralisObjects ACL. You can check the LiveQuery protocol here for more details.
The subscription you get is the same subscription you receive from our Standard API. You can check our Standard API about how to use the subscription to get events.

Unsubscribe

1
client.unsubscribe(subscription);
Copied!
  • subscription (required): It's the subscription you want to unsubscribe from.
    After you call this, you won't get any events from the subscription object.

Close

1
client.close();
Copied!
This function will close the WebSocket connection to this LiveQueryClient, cancel the auto-reconnect, and unsubscribe all subscriptions based on it.

Event Handling

We expose three events to help you monitor the status of the LiveQueryClient.

Open Event

1
client.on('open', () => {
2
console.log('connection opened');
3
});
Copied!
When we establish the WebSocket connection to the LiveQuery server, you'll get this event.

Close Event

1
client.on('close', () => {
2
console.log('connection closed');
3
});
Copied!
When we lose the WebSocket connection to the LiveQuery server, you'll get this event.

Error Event

1
client.on('error', (error) => {
2
console.log('connection error');
3
});
Copied!
When a network error or LiveQuery server error happens, you'll get this event.

Reconnect

Since the whole LiveQuery feature relies on the WebSocket connection to the LiveQuery server, we always try to maintain an open WebSocket connection.
Thus, when the connection is lost to the LiveQuery server, we try to auto-reconnect. We do exponential back off under the hood.
However, if the WebSocket connection is closed due to Moralis.LiveQuery.close() or client.close(), we'll cancel the auto-reconnect.

SessionToken

We send sessionToken to the LiveQuery server when you subscribe to a MoralisQuery. For the standard API, we use the sessionToken of the current user by default. For the advanced API, you can use any sessionToken when you subscribe to a MoralisQuery. An important thing to be aware of is when you log out or the sessionToken you are using is invalid, you should unsubscribe from the subscription and subscribe to the MoralisQuery again. Otherwise, you may face a security issue since you'll get events that shouldn't be sent to you.
Last modified 2mo ago