Manage Sync Subscriptions - Kotlin SDK

Subscribe to Object Types

Subscription sets are based on object type. You might have multiple subscriptions if you have many types of Realm objects. You can also have multiple subscriptions on the same object type.

However, if you use linked objects, asymmetric objects, or geospatial data in your app, refer the following sections for additional information:

Initial Subscriptions

You must have at least one subscription before you can read from or write to the realm.

Subscribe to a Query

You can .subscribe() to a query to create a subscription for objects matching a specific query:

// Subscribe to a specific query
val realmResults = realm.query<Task>("progressMinutes >= $0", 60)
    .subscribe()
// Subscribe to all objects of a specific type
val realmQuery = realm.query<Team>()
realmQuery.subscribe()

This creates an unnamed subscription and adds it to the MutableSubscriptionSet, instead of requiring you to manually add the subscription to the subscription set.

// Add a subscription named "team_developer_education"
val results = realm.query<Team>("teamName == $0", "Developer Education")
    .subscribe("team_developer_education")

Update a Query Subscription

You can update a named query subscription with a new query by setting updateExisting to true:

// Create a subscription named "bob_smith_teams"
val results = realm.query<Team>("$0 IN members", "Bob Smith")
    .subscribe("bob_smith_teams")
// Add another subscription with the same name with `updateExisting` set to true
// to replace the existing subscription
val updateResults =
        realm.query<Team>("$0 IN members AND teamName == $1", "Bob Smith", "QA")
            .subscribe("bob_smith_teams", updateExisting = true)

This updates the subscription automatically, instead of requiring you to manually update the subscription in the subscription set.

Wait for a Query Subscription to Sync

When you subscribe to a query's results set, that set does not contain objects until it syncs. If your app creates objects, you may not need to download synced data before the user works with it. However, if your app requires data from the server before the user can work with it, you can specify that the app should wait for data to sync. This blocks app execution until data syncs from the server.

val results = realm.query<Team>("$0 IN members", "Bob Smith")
    .subscribe("bob_smith_teams", updateExisting = false, WaitForSync.ALWAYS)
// After waiting for sync, the results set contains all the objects
// that match the query - in our case, 1
println("The number of teams that have Bob Smith as a member is ${results.size}")

This option uses the WaitForSync enum, whose values are:

• FIRST_TIME: (Default) Wait to download matching objects when your app initially creates the subscription. Otherwise, return without waiting for new downloads. The app must have an internet connection to download the data when you initially add the subscription. You can optionally specify a timeout value.

• ALWAYS: Wait to download matching objects every time the .subscribe() method is called. The app must have an internet connection to download the data. You can optionally specify a timeout value.

• NEVER: Never wait to download matching objects. The app needs an internet connection for the user to authenticate the first time the app launches but can open offline on subsequent launches using cached credentials.

Add a Subscription

You can add an unnamed subscription or a named subscription.

To manually create a subscription, add the subscription in a subscriptions update block. You append each new subscription to the client's Realm subscriptions.

realm.subscriptions.update {
    add(
        realm.query<Task>("progressMinutes >= $0",60)
    )
}

You can also specify a subscription name when you create the subscription:

// Add a subscription named "team_dev_ed"
realm.subscriptions.update { realm ->
        add(
            realm.query<Team>("teamName == $0", "Developer Education"),
            name = "team_dev_ed"
        )
    }

// Bootstrap the realm with an initial query to subscribe to
val flexSyncConfig =
    SyncConfiguration.Builder(user, setOf(Team::class, Task::class))
        .initialSubscriptions { realm ->
            add(
                realm.query<Team>("$0 IN members", "Bob Smith"),
                "bob_smith_teams"
            )
        }
        .build()

// `rerunOnOpen` lets the app recalculate this query every time the app opens
val rerunOnOpenConfig =
    SyncConfiguration.Builder(user, setOf(Team::class, Task::class))
        .initialSubscriptions(rerunOnOpen = true) { realm ->
            add(
                realm.query<Team>("completed == $0", false)
            )
        }
        .build()

Wait for Subscription Changes to Sync

Writing an update to the subscription set locally is only one component of changing a subscription. After the local subscription change, the client 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 SyncConfiguration.waitForInitialRemoteData() builder method to force your application to block until client subscription data synchronizes to the backend before opening the realm:

// Update the list of subscriptions
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Jane Doe"),
        "jane_doe_teams"
    )
}
// Wait for subscription to fully synchronize changes
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))

You can also use SubscriptionSet.waitForSynchronization() to delay execution until subscription sync completes after instantiating a sync connection.

Subscription Set State

Use the SubscriptionSet.state property to read the current state of the subscription set.

SUPERCEDED (sic -- note alternate spelling) is a SubscriptionSetState that can occur when another thread writes a subscription on a different instance of the subscription set. If the state becomes SUPERCEDED, you must obtain a new instance of the subscription set before you can write to it.

Update Subscriptions with a New Query

You can update subscriptions using SubscriptionSet.update().

In this example, we use MutableSubscriptionSet.add(). to update the query for the subscription named "bob_smith_teams". You must set the updateExisting parameter to true to update a subscription with add():

// Create a subscription named "bob_smith_teams"
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams"
    )
}
// Set `updateExisting` to true to replace the existing
// "bob_smith_teams" subscription
realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members AND $1 IN members", "Bob Smith", "Jane Doe"),
        "bob_smith_teams", updateExisting = true
    )
}

You cannot update subscriptions created without a name. However, you can look up unnamed subscriptions by their query, remove them from the subscription set, then add a new subscription with an updated query:

// Search for the subscription by query
val subscription =
    realm.subscriptions.findByQuery(
        realm.query<Team>("teamName == $0", "Developer Education")
    )
// Remove the returned subscription and add the updated query
if (subscription != null) {
    realm.subscriptions.update {
        remove(subscription)
        add(
            realm.query<Team>("teamName == $0", "DevEd"),
            "team_developer_education"
        )
    }
}

Remove Subscriptions

To remove subscriptions, you can:

• Remove a single subscription query

• Remove all subscriptions to a specific object type

• Remove all subscriptions

• Remove all unnamed subscriptions

When you remove a subscription query, Realm asynchronously removes the synced data that matched the query from the client device.

realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams"
    )
}
// Wait for synchronization to complete before updating subscriptions
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))
// Remove subscription by name
realm.subscriptions.update {
    remove("bob_smith_teams")
}

realm.subscriptions.update {
    add(
        realm.query<Team>("$0 IN members", "Bob Smith"),
        "bob_smith_teams")
}
// Wait for synchronization to complete before updating subscriptions
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))
// Remove all subscriptions to type Team
realm.subscriptions.update {
    removeAll(Team::class)
}

// Remove all subscriptions
realm.subscriptions.update {
    removeAll()
}

// Remove all unnamed (anonymous) subscriptions
realm.subscriptions.update {
    removeAll(anonymousOnly = true)
}

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

Query Size Limit

The size limit for any given query subscription in your subscription set is 256 kB. Exceeding this limit results in a LimitsExceeded Error.

API Efficiency

Managing multiple subscriptions with the .subscribe() API described in the Subscribe to Queries section is less efficient than performing batch updates when you manually manage subscriptions through the subscription set API. For better performance when making multiple subscription changes, use the subscriptions.update API described in the Manually Manage Subscriptions section.

Group Updates for Improved Performance

Every write transaction for a subscription set has a performance cost. If you need to make multiple updates to a Realm object during a session, consider keeping edited objects in memory until all changes are complete. This improves sync performance by only writing the complete and updated object to your realm instead of every change.