subscribe

Query subscriptions are the "live" version of a fetch. Subscribing to a query will provide continual updates to the query result based on the state of your local database.

If the sync engine is connected to the remote database, subscribing to a query will keep your local database in sync with the remote database as well depending on the options provided to the subscription.

Starting a subscription is as simple as defining a query and a callback to run when data has updated:

const unsubscribe = client.subscribe(
  query,
  (results, info) => {
    // handle results
  },
  (error) => {
    // handle error
  },
  // Optional
  {
    localOnly: false,
    onRemoteFulfilled: () => {
      console.log('server has sent back results for the subscription');
    },
  }
);

If a subscription query fails on the server then syncing for that query will stop. However, the subscription will remain active and updates to the local database will still be available. As well, the syncing of other queries will not be impacted. Although you will not receive updates from the server, updates that you make via mutations will be sent.

Subscription options

• syncStatus: Describes the set of data from the client's various sources to include in the subscription. Can be pending, confirmed, or all. By default, syncStatus is set to all.
• localOnly: If set to true, the subscription will only listen to changes in the local database and will not attempt to sync with the remote database. Multiple small localOnly subscriptions are often paired with a large background subscription. By default, localOnly is set to false.
• onRemoteFulfilled: A callback that is called when the server has first sent back results for the subscription.