Manage Sync Subscriptions - Flutter SDK

Get Subscriptions

When using Flexible Sync, you can access a SubscriptionSet, a collection of subscriptions, through the Realm.subscriptions property.

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

final subscriptions = realm.subscriptions;

Add a Query to the Set of Subscriptions

You must perform all mutations on the subscriptions set within an update block. To create an update block, call SubscriptionSet.update().

The update block callback function includes a MutableSubscriptionSet() object as an argument. You can modify your method on the SubscriptionSet to add a query to the subscription.

The MutableSubscriptionSet.add() method takes three arguments:

• RealmResults query: Required. A RealmResults object that you can create using the Realm Query Language query.

• String name: Optional. Name for the subscription that you can refer to.

• bool update: Optional. When true, adding a subscription with an existing name replaces the existing query with the new query. Only use with named subscriptions.

You can add a single query, or batch multiple queries within a SubscriptionSet.update block. Performing query updates is an expensive operation on the server. We strongly advise designing your application to minimize subscription updates. You can do this by creating all subscriptions in a single update block the first time the user launches the app and batching any follow-up changes to the subscription set.

In the example below, we subscribe to two queries.

final planeQuery = realm.all<Plane>();
final longTrainQuery = realm.query<Train>("numCars >= 5");
realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.add(planeQuery, name: "planes");
  mutableSubscriptions.add(longTrainQuery,
      name: 'long-trains', update: true);
});
await realm.subscriptions.waitForSynchronization();

Update Subscriptions with a New Query

You can update a named subscription with a new query. To update a subscription's query, open an update block with SubscriptionSet.update(). In the callback function of the update block, pass the following arguments to MutableSubscriptionSet.add():

• The new query

• The name of the subscription that you want to update

• update: true

You cannot update an unnamed subscription. Alternatively, you can delete the unnamed subscription, and create a new subscription with the desired query.

In the following example, long trains are re-defined to be any trains that have more than 10 cars.

final longerTrainQuery = realm.query<Train>("numCars > 10");
realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.add(longerTrainQuery,
      name: 'long-trains', update: true);
});

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 a single subscription with the subscription reference

• Remove all subscriptions for a Realm object type

• Remove all subscriptions

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

realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.removeByQuery(realm.all<Plane>());
});

realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.removeByName('long-trains');
});

final sub = realm.subscriptions[0];
realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.remove(sub);
});

realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.removeByType<Train>();
});

realm.subscriptions.update((MutableSubscriptionSet mutableSubscriptions) {
  mutableSubscriptions.clear();
});

Wait for Subscription Changes to Sync

Mutating the subscription set within an update block is only one part of changing a subscription. After the local subscription change, the realm synchronizes with the server to resolve any updates to the data due to the subscription change. This includes adding or removing data from the synced realm.

Use Realm.subscriptions.waitForSynchronization() to wait for the server to acknowledge this set of subscriptions. If the server rejects the change, and an exception is thrown.

An exception may occur if:

• You subscribe to an unsupported query. Subscribing to an unsupported query will pause synchronization. To resume synchronization, remove the unsupported query.

• You are performing an invalid action, such as adding an object that does not match a subscription. This triggers a client reset: data is erased from the realm, and a new copy of the data is created without any subscriptions in the set.

await realm.subscriptions.waitForSynchronization();

Subscription State

Use the Realm.subscriptions.state property to read the current state of the subscription set.

The superseded state is a SubscriptionSetState that can occur when another thread updates a subscription on a different instance of the subscription set. If the state becomes superseded, you must obtain a new instance of the subscription set before you can update it.

Indexed Queryable Fields Subscription Requirements

Adding an indexed queryable field to your App can improve performance for simple queries on data that is strongly partitioned. For example, an app where queries strongly map data to a device, store, or user, such as user_id == $0, “641374b03725038381d2e1fb”, is a good candidate for an indexed queryable field. However, an indexed queryable field has specific requirements for use in a query subscription:

• The indexed queryable field must be used in every subscription query. It cannot be missing from the query.

• The indexed queryable field must use an == or IN comparison against a constant at least once in the subscription query. For example, user_id == $0, "641374b03725038381d2e1fb" or store_id IN $0, {1,2,3}.

You can optionally include an AND comparison as long as the indexed queryable field is directly compared against a constant using == or IN at least once. For example, store_id IN {1,2,3} AND region=="Northeast" or store_id == 1 AND (active_promotions < 5 OR num_employees < 10).

Invalid Flexible Sync queries on an indexed queryable field include queries where:

• The indexed queryable field does not use AND with the rest of the query. For example store_id IN {1,2,3} OR region=="Northeast" is invalid because it uses OR instead of AND. Similarly, store_id == 1 AND active_promotions < 5 OR num_employees < 10 is invalid because the AND only applies to the term next to it, not the entire query.

• The indexed queryable field is not used in an equality operator. For example store_id > 2 AND region=="Northeast" is invalid because it uses only the > operator with the indexed queryable field and does not have an equality comparison.

• The query is missing the indexed queryable field entirely. For example, region=="Northeast or truepredicate are invalid because they do not contain the indexed queryable field.

Unsupported Query Operators in Flexible Sync

Flexible Sync has some limitations when using RQL operators. When you write the query subscription that determines which data to sync, the server does not support these query operators. However, you can still use the full range of RQL features to query the synced data set in the client application.

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".