Manage Flexible Sync Subscriptions - Node.js SDK

Get Subscriptions

When using a flexible synced realm, you can access a SubscriptionSet, a collection of subscriptions, through the realm.subscriptions property.

// get the SubscriptionSet for the realm
const subscriptions = realm.subscriptions;

You can use this SubscriptionSet to add queries to the list of subscriptions and update existing subscriptions, as shown in the examples below.

Add a Query to the List Of Subscriptions

Compose queries to add to your Flexible Sync subscriptions using the query engine:

const tasks = realm.objects("Task");
const longRunningTasks = tasks.filtered(
  'status == "completed" && progressMinutes > 120'
);
const bensTasks = tasks.filtered('owner == "Ben"');

Add queries to your subscriptions list to sync the query's data. To do so, perform the following:

1. Create a transaction by passing a callback function to the SubscriptionSet.update() method of your SubscriptionSet. The callback function provides a MutableSubscriptionSet as an argument.

2. Within the callback function, call the add() method on the MutableSubscriptionSet to add a query to the subscription.

The following example shows how to subscribe to the queries created above.

await realm.subscriptions.update((mutableSubs) => {
  mutableSubs.add(longRunningTasks, {
    name: "longRunningTasksSubscription",
  });
  mutableSubs.add(bensTasks);
  mutableSubs.add(realm.objects("Team"), {
    name: "teamsSubscription",
    throwOnUpdate: true,
  });
});

The add() method on the MutableSubscriptionSet takes a query and a SubscriptionOptions object. The subscription options include:

• a name string field

• a throwOnUpdate boolean field.

If throwOnUpdate is false or undefined, adding a subscription with an existing name will replace the existing query with the new query. However, if you set throwOnUpdate to true, adding a subscription with an existing name but a different query throws an exception.

const config = {
  sync: {
    user: app.currentUser,
    flexible: true,
    initialSubscriptions: {
      update: (subs, realm) => {
        subs.add(
          realm.objects("Team").filtered("name == 'Developer Education'")
        );
      },
    },
  },
};
const realm = await Realm.open(config);

Check the Status of Subscriptions

You can check the subscription state to see if the server has acknowledged the subscription and the device has downloaded the data locally.

You can use subscription state to:

• Trigger error handling

• Show if the transaction is pending or has completed

• Find out when a subscription set is superseded, and you should obtain a new instance of the subscription set to write a subscription change

To the status of subscriptions, log the value of the subscription's state.

console.log(realm.subscriptions.state); // log the subscription state

Update Subscriptions with a New Query

You can update a named subscription with a new query. To update a subscriptions query, pass the new query and a subscription option with the name of the subscription that you want to update to the MutableSubscriptionSet.add() method. Like adding a new subscription, you must update a subscription within a transaction by calling subscriptions.update() method.

In the following example, long-running tasks are re-defined to be any tasks that have taken more than 180 minutes.

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.add(
    tasks.filtered('status == "completed" && progressMinutes > 180'),
    {
      name: "longRunningTasksSubscription",
    }
  );
});

Remove Subscriptions

To remove subscriptions from the subscription set, you can:

• Remove a single subscription with the given query

• Remove a single subscription with the given name

• Remove all subscriptions on a specific type

• Remove all subscriptions

When you remove a subscription query, the server also removes synced data from the client device.

realm.subscriptions.update((mutableSubs) => {
  // remove a subscription with a specific query
  mutableSubs.remove(tasks.filtered('owner == "Ben"'));
});

realm.subscriptions.update((mutableSubs) => {
  // remove a subscription with a specific name
  mutableSubs.removeByName("longRunningTasksSubscription");
});

let subscriptionReference;
realm.subscriptions.update((mutableSubs) => {
  subscriptionReference = mutableSubs.add(realm.objects("Task"));
});
// later..
realm.subscriptions.removeSubscription(subscriptionReference);

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeByObjectType("Team");
});

realm.subscriptions.update((mutableSubs) => {
  mutableSubs.removeAll();
});

Unsupported Query Operators in Flexible Sync

Case insensitive queries ([c]) cannot use indexes effectively. As a result, case insensitive queries are not recommended, since they could lead to performance problems.

Flexible Sync only supports @count for array fields.

List Queries

Flexible Sync supports querying lists using the IN operator.

You can query a list of constants to see if it contains the value of a queryable field:

// Query a constant list for a queryable field value
"priority IN { 1, 2, 3 }"

If a queryable field has an array value, you can query to see if it contains a constant value:

// Query an array-valued queryable field for a constant value
"'comedy' IN genres"

// Invalid Flexible Sync query. Do not do this!
"{'comedy', 'horror', 'suspense'} IN genres"
// Another invalid Flexible Sync query. Do not do this!
"ANY {'comedy', 'horror', 'suspense'} != ANY genres"

Embedded or Linked Objects

Flexible Sync does not support querying on properties in Embedded Objects or links. For example, obj1.field == "foo".