Manage Flexible Sync Subscriptions- .NET SDK

Get Subscriptions

When using flexible sync, you can access a SubscriptionSet, a collection of subscriptions, through the Realm.Subscriptions property.

var subscriptions = realm.Subscriptions;

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

Add a Query to the Set Of Subscriptions

You must have at least one subscription before you can read from or write to the realm. You can create one or more initial subscriptions when you configure Flexible Sync, or you can add subscriptions after initialization.

var config = new FlexibleSyncConfiguration(app.CurrentUser)
{
    PopulateInitialSubscriptions = (realm) =>
    {
        var myItems = realm.All<Item>().Where(n => n.OwnerId == myUserId);
        realm.Subscriptions.Add(myItems);
    }
};
// The process will complete when all the user's items have been downloaded.
var realm = await Realm.GetInstanceAsync(config);

realm.Subscriptions.Update(() =>
{
    // subscribe to all long running tasks, and give the subscription the name 'longRunningTasksSubscription'
    var longRunningTasksQuery = realm.All<Task>().Where(t => t.Status == "completed" && t.ProgressMinutes > 120 );
    realm.Subscriptions.Add(longRunningTasksQuery, new SubscriptionOptions() { Name = "longRunningTasks" });
    // subscribe to all of Ben's Task objects
    realm.Subscriptions.Add(realm.All<Task>().Where(t => t.Owner == "Ben"));
    // subscribe to all Teams, and give the subscription the name 'teamsSubscription' and throw an error if a new query is added to the team subscription
    realm.Subscriptions.Add(realm.All<Team>(), new SubscriptionOptions() { Name = "teams", UpdateExisting = false }); 
});

Update Subscriptions with a New Query

You can update a named subscription with a new query. To update a subscription's query, pass the new query and a subscription option with the name of the subscription that you want to update to the SubscriptionSet.Add() method. Like adding a new subscription, you must update a subscription within an update block by calling SubscriptionSet.Update() method.

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

realm.Subscriptions.Update(() =>
{
    var updatedLongRunningTasksQuery = realm.All<Task>().Where(t => t.Status == "completed" && t.ProgressMinutes > 130);
    realm.Subscriptions.Add(updatedLongRunningTasksQuery, new SubscriptionOptions() { Name = "longRunningTasks" });
});

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 given subscription

• Remove all subscriptions of 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(() =>
{
    // remove a subscription by it's query
    var query = realm.All<Task>().Where(t => t.Owner == "Ben");
    realm.Subscriptions.Remove(query);
});

realm.Subscriptions.Update(() =>
{
    // remove a named subscription
    var subscriptionName = "longRunningTasksSubscription";
    realm.Subscriptions.Remove(subscriptionName);
});

realm.Subscriptions.Update(() =>
{
    // remove all subscriptions of the "Team" Class Name 
    realm.Subscriptions.RemoveAll("Team");
    // Alernatively, remove all subscriptions of the "Team" object type
    realm.Subscriptions.RemoveAll<Team>();
});

realm.Subscriptions.Update(() =>
{
    // remove all subscriptions, including named subscriptions
    realm.Subscriptions.RemoveAll(true);
});

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 could mean adding or removing data from the synced realm.

Use the SubscriptionSet.WaitForSynchronizationAsync() method to wait for the server to acknowledge this set of subscriptions. If the server rejects the change, the SubscriptionSetState will be an error state, and an exception will be thrown.

An exception may occur if:

• an unsupported query is subscribed to. 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.

// Wait for the server to acknowledge the subscription change and return all objects
// matching the query
try
{
    await realm.Subscriptions.WaitForSynchronizationAsync();
}
catch (SubscriptionException ex)
{
    // do something in response to the exception or log it
    Console.WriteLine($@"The subscription set's state is Error and synchronization is paused:  {ex.Message}");
}

Subscription State

Use the SubscriptionSet.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.

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