A Live Query keeps a query open over a WebSocket: when an object that matches it is created, changed or deleted, your app gets the event right away. Chats, dashboards, collaborative lists and notifications in the app are typical uses.
1. Enable the classes
In the dashboard open App Settings › Live Queries and tick the classes clients may subscribe to. Only these classes send events. Saving the settings redeploys the app.
2. Subscribe from the client
The WebSocket URL is in App Settings › Security & Keys › LiveQuery URL Address: your API URL with wss://.
import Parse from 'parse';
Parse.initialize('YOUR_APP_ID', 'YOUR_JAVASCRIPT_KEY');
Parse.serverURL = 'https://pg-app-<id>.scalabl.cloud/1/';
Parse.liveQueryServerURL = 'wss://pg-app-<id>.scalabl.cloud/1/';
const query = new Parse.Query('Message');
query.equalTo('room', 'general');
const subscription = await query.subscribe();
subscription.on('create', (message) => console.log('new', message.get('text')));
subscription.on('update', (message) => console.log('changed', message.id));
subscription.on('delete', (message) => console.log('deleted', message.id));Events:
| Event | When |
|---|---|
open |
The subscription is ready |
create |
A new object matches the query |
update |
A matching object changed and still matches |
enter |
An object changed and now matches |
leave |
An object changed and no longer matches |
delete |
A matching object was deleted |
close |
The connection closed |
Call subscription.unsubscribe() when the screen goes away. The SDKs for iOS, Android and Flutter have the same API: see Parse's Live Query guide.
Permissions
A subscriber gets an event only for objects it could read: the class's Find permission must allow the user, and the object's ACL must let them read it. Log the user in before subscribing, so their session goes with the subscription. Events for objects the user can't read are never sent.
Several instances
A Live Query connection stays on one instance of your app. With more than one instance (auto-scaling, or high availability), an object saved through another instance must reach the subscribers too, which needs a message broker: contact support to add Redis for Live Queries. Until then, run the app on one instance with auto-scaling off.
Tips
- Subscribe to narrow queries (
equalTo('room', ...)), not whole classes: every matching save is sent to every subscriber. - Changes made with the master key, from cloud code or the dashboard, send events too.
- Live Queries complement queries, they don't replace them: load the current data with
find(), then subscribe for the changes.