Manage Sync Subscriptions - Kotlin SDK

Prerequisites

To use Flexible Sync in the SDK:

• Configure Flexible Sync on the backend

• Authenticate a user in your client app.

• Open the synced Realm with a Flexible Sync configuration

You can add, update, and remove query subscriptions to determine which data syncs to the client device.

Subscriptions

When you configure Flexible Sync on the backend, you specify which fields your client application can query. In the client application, use the subscriptions API to manage a set of subscriptions to specific queries on queryable fields. You can construct queries with Realm Query Language.

You can:

• Add subscriptions

• React to subscription state

• Update subscriptions with new queries

• Remove individual subscriptions or all subscriptions for an object type

Data matching the subscription, where the user has the appropriate permissions, syncs between clients and the backend application.

You can specify an optional string name for your subscription.

When you create a subscription, Realm looks for data matching a query on a specific object type. You can create multiple subscription sets on different object types, and even query multiple times on the same object type.

Subscription names must be unique. Adding a subscription with the same name as an existing subscription throws an error.

Add a Subscription

Add a subscription in a subscriptions update block. You append each new subscription to the client's Realm subscriptions.

realm.subscriptions.update {
    this.add(
        realm.query<Toad>("name == $0", "another name value"),
        "another subscription name"
    )
}

// make an update to the list of subscriptions
realm.subscriptions.update {
    this.add(
        realm.query<Toad>("name == $0", "another name value"),
        "another subscription name"
    )
}
// wait for subscription to fully synchronize changes
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))

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 "subscription name". You must set the updateExisting parameter to true to update a subscription with add():

// create an initial subscription named "subscription name"
val config = SyncConfiguration.Builder(user, setOf(Toad::class))
    .initialSubscriptions { realm ->
        add(
            realm.query<Toad>(
                "name == $0",
                "name value"
            ),
            "subscription name"
        )
    }
    .build()
val realm = Realm.open(config)
// to update that subscription, add another subscription with the same name
// it will replace the existing subscription
realm.subscriptions.update {
    this.add(
        realm.query<Toad>("name == $0", "another name value"),
        "subscription name",
        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:

val subscription =
    realm.subscriptions.findByQuery(
        realm.query<Toad>("name == $0", "name value")
    )
if (subscription != null) {
    realm.subscriptions.update {
        this.remove(subscription)
        this.add(
            realm.query<Toad>(
                "name == $0",
                "another name value"
            ),
            "subscription name"
        )
    }
}

Remove Subscriptions

To remove subscriptions, you can:

• Remove a single subscription query

• Remove all subscriptions to a specific object type

• Remove all subscriptions

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

// create an initial subscription named "subscription name"
val config = SyncConfiguration.Builder(user, setOf(Toad::class))
    .initialSubscriptions { realm ->
        add(
            realm.query<Toad>(
                "name == $0",
                "name value"
            ),
            "subscription name"
        )
    }
    .build()
val realm = Realm.open(config)
// remove subscription by name
realm.subscriptions.update {
    this.remove("subscription name")
}

// create an initial subscription named "subscription name"
val config = SyncConfiguration.Builder(user, setOf(Toad::class))
    .initialSubscriptions { realm ->
        add(
            realm.query<Toad>(
                "name == $0",
                "name value"
            ),
            "subscription name"
        )
    }
    .build()
val realm = Realm.open(config)
// wait for synchronization to complete before editing subscriptions
realm.subscriptions.waitForSynchronization(Duration.parse("10s"))
// remove all subscriptions to type Toad
realm.subscriptions.update {
    this.removeAll(Toad::class)
}

// create an initial subscription named "subscription name"
val config = SyncConfiguration.Builder(user, setOf(Toad::class))
    .initialSubscriptions { realm ->
        add(
            realm.query<Toad>(
                "name == $0",
                "name value"
            ),
            "subscription name"
        )
    }
    .build()
val realm = Realm.open(config)
// remove all subscriptions
realm.subscriptions.update {
    this.removeAll()
}

Flexible Sync RQL Limitations

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.

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

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