Fetching data
Subscriptions

Subscriptions

Alternatively, you may subscribe to a query. 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.

subscribeWithPagination

subscribeWithPagination is a special type of subscription that is used to fetch data in pages. It is similar to subscribe but it has a few differences:

  • It expects the query to have a limit defined.
  • It returns nextPage and prevPage functions to fetch the next and previous pages of data.
  • The subscription callback will have hasNextPage and hasPreviousPage booleans to indicate if there are more pages to fetch.
const { unsubscribe, nextPage, prevPage } = client.subscribeWithPagination(
  query,
  (results, { hasRemoteFulfilled, hasNextPage, hasPreviousPage }) => {
    // handle results
  },
  (error) => {
    // handle error
  },
  // Optional
  {
    localOnly: false,
    onRemoteFulfilled: () => {
      console.log('server has sent back results for the subscription');
    },
  }
);

subscribeWithExpand

subscribeWithExpand is a special type of subscription that is used to fetch a window of data that can programmatically grow in size. It is similar to subscribe but it has a few differences:

  • It expects the query to have an initial limit defined.
  • It returns a loadMore(pageSize?: number) function to fetch more data. By default, it fetches the next page of data based on the initial limit defined in the query.
const { unsubscribe, loadMore } = client.subscribeWithExpand(
  query,
  (results, info) => {
    // handle results
  },
  (error) => {
    // handle error
  },
  // Optional
  {
    localOnly: false,
    onRemoteFulfilled: () => {
      console.log('server has sent back results for the subscription');
    },
  }
);