Page updated Jan 16, 2024

Observe in real time

Observe model mutations in real-time

You can subscribe to changes on your Models. This reacts dynamically to updates of data to the underlying Storage Engine, which could be the result of GraphQL Subscriptions as well as Queries or Mutations that run against the backing AppSync API if you are synchronizing with the cloud.

const subscription = DataStore.observe(Post).subscribe(msg => { console.log(msg.model, msg.opType, msg.element); });
1const subscription = DataStore.observe(Post).subscribe(msg => {
2 console.log(msg.model, msg.opType, msg.element);
3});

Observing changes of a single item by ID.

const id = '69ddcb63-7e4a-4325-b84d-8592e6dac07b'; const subscription = DataStore.observe(Post, id).subscribe(msg => { console.log(msg.model, msg.opType, msg.element); });
1const id = '69ddcb63-7e4a-4325-b84d-8592e6dac07b';
2
3const subscription = DataStore.observe(Post, id).subscribe(msg => {
4 console.log(msg.model, msg.opType, msg.element);
5});

Closing a subscription:

const subscription = DataStore.observe(Post, id).subscribe(msg => { console.log(msg.model, msg.opType, msg.element); }); // Call unsubscribe to close the subscription subscription.unsubscribe();
1const subscription = DataStore.observe(Post, id).subscribe(msg => {
2 console.log(msg.model, msg.opType, msg.element);
3});
4
5// Call unsubscribe to close the subscription
6subscription.unsubscribe();

The observe function is asynchronous; however, you should not use await like the other DataStore API methods since it is a long running task and you should make it non-blocking (i.e. code after the DataStore.observe() call should not wait for its execution to finish).

DataStore.clear() will remove any active subscriptions. You'll need to re-establish them manually by calling DataStore.observe() again after you clear.

Observe query results in real-time

observeQuery(...) returns an initial data set, similar to query(...), and also automatically subscribes to subsequent changes to the query.

The first snapshot returned from observeQuery will contain the same results as calling query directly on your Model - a collection of all the locally-available records. Subsequent snapshots will be emitted as updates to the dataset are received in the local store.

While data is syncing from the cloud, snapshots will contain all of the items synced so far and an isSynced status of false. When the sync process is complete, a snapshot will be emitted with all the records in the local store and an isSynced status of true.

In addition to typical real-time use cases, observeQuery can be used on app launch to show your customers an initial data set from the local store while new data is being synced from cloud.

observeQuery also accepts the same predicates and sorting options as query.

const subscription = DataStore.observeQuery( Post, p => p.and(p => [ p.title.beginsWith("post"), p.rating.gt(10) ]), { sort: s => s.rating(SortDirection.ASCENDING) } ).subscribe(snapshot => { const { items, isSynced } = snapshot; console.log(`[Snapshot] item count: ${items.length}, isSynced: ${isSynced}`); });
1const subscription = DataStore.observeQuery(
2 Post,
3 p => p.and(p => [
4 p.title.beginsWith("post"),
5 p.rating.gt(10)
6 ]), {
7 sort: s => s.rating(SortDirection.ASCENDING)
8 }
9).subscribe(snapshot => {
10 const { items, isSynced } = snapshot;
11 console.log(`[Snapshot] item count: ${items.length}, isSynced: ${isSynced}`);
12});

The default configuration for observeQuery has a default syncPageSize of 1,000 and a default maxRecordsToSync of 10,000. These values can be customized by configuring their values manually in DataStore.configure.