Query Change Listeners Tutorial

Add change listeners to a query and automatically retrieve real-time query updates. When registering a Query Change Listener, you can know when your object graph has been updated and use it to indicate when to refresh your UI without having to execute another query.

Steps to Use Query Change Listeners (Onyx Cloud Database)

1

Define a Query with Criteria

Use the QueryCriteria and Query classes to define your query.
1db.from('Player')
2    .where(eq("position", "QB"))
3    .and(eq("isHallOfFame", true))
2

Define a Change Listener on the Query

Add a change listener to your query to receive real-time updates when the query results change.
1const query =
2    db.from('Player')
3      .where(eq("position", "QB"))
4      .and(eq("isHallOfFame", true))
5      .onItemUpdated((item) => {
6          console.log(`Player ${item.firstName} ${item.lastName} has been updated!`);
7      })
8      .onItemAdded((item) => {
9          console.log(`Player ${item.firstName} ${item.lastName} has been added!`);
10      });
3

Execute the Query

Query Change Listeners are registered automatically when invoking either the executeQuery or executeLazyQuery methods. The keepAlive parameter is required in order to keep the stream alive after executing the query.
1const handle = await query.stream(false, true);
4

Save, Delete, or Update an Entity Matching the Query Criteria

Perform operations on entities that match the query criteria to see how the change listener reacts.
1const tomBrady = {
2    firstName: "Tom",
3    lastName: "Brady",
4    position: "QB",
5    isHallOfFame: true
6};
7
8// On Item Added should be fired
9await db.save('Player', tomBrady);
10
11// He was ejected from the Hall of Fame
12tomBrady.isHallOfFame = false;
13// See that he was removed from the result set and the onItemRemoved was fired
14await db.save('Player', tomBrady);
15
16// Modify an entity and save, the onItemUpdated should be fired
17johnElway.didNotCheat = true;
18await db.save('Player', johnElway);
5

Remove the Query Change Listener When Finished

It is always a good practice to clean up listeners to prevent memory leaks and optimize performance.
1// Remove the change listener when done
2await handle.cancel();
Next Tutorial: Querying Entities

Important Notes

  • Be cautious when registering a large number of unique queries with change listeners, as it may impact performance.
  • Always unregister your Query Change Listeners when they are no longer needed to prevent memory leaks and performance degradation.
  • Query Change Listeners are not registered when using executeDelete or executeUpdate methods.

Troubleshooting

  • Change Listener Not Triggering: Ensure that the query is executed after setting the change listener.
  • Memory Leak Issues: Verify that you are unregistering change listeners when they are no longer needed.
  • Performance Degradation: Limit the number of registered queries with change listeners to optimize performance.

Next Steps

Now that you have learned how to use Query Change Listeners, you can explore more advanced querying techniques: