Docs Menu

Subscribe to Queryable Fields - Kotlin SDK

On this page

Flexible Sync uses subscriptions and permissions to determine which data to sync with your App.

To use Flexible Sync in the SDK:

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

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.

Important

Flexible Sync does not support all the operators available in Realm Query Language. See Flexible Sync RQL Limitations for details.

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.

Note
Always Specify a Subscription Name

Always specify a subscription name if your application uses multiple subscriptions. This makes your subscriptions easier to look up, update, and delete elsewhere in your app.

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 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")
}
Important
Object Links

You must add both an object and its linked object to the subscription set to see a linked object.

If your subscription results contain an object with a property that links to an object not contained in the results, the link appears to be nil. There is no way to distinguish whether that property's value is legitimately nil, or whether the object it links to exists but is out of view of the query subscription.

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 SynConfiguration.waitForInitialRemoteData() builder method to force your application to block until client subscription data synchronizes to the backend before opening the realm:

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

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

Additionally, you can watch the state of the subscription set with the SubscriptionSetState enum. You can use subscription state to:

  • Show a progress indicator while data is downloading
  • Find out when a subscription set becomes superseded

You can access the state of your application's subscription set using SubscriptionSet.state.

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

You can update subscriptions using SubscriptionSet.update(). In this example, we use MutableSubscriptionSet.add(). to update the query for the subscription named "my frog subscription". 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"
)
}
}

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.

You can remove a specific subscription query using MutableSubscriptionSet.remove(). You can either look up the subscription by name, then pass the returned subscription to remove(), or pass the subscription name directly to remove():

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

If you want to remove all subscriptions to a specific object type, pass a class to the MutableSubscriptionSet.removeAll(). method:

// 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 to type Toad
realm.subscriptions.update {
this.removeAll(Toad::class)
}

To remove all subscriptions from the subscription set, use MutableSubscriptionSet.removeAll(). with no arguments:

Important

If you remove all subscriptions and do not add a new one, you'll get an error. A realm opened with a flexible sync configuration needs at least one subscription to sync with the server.

// 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()
}
←  Open a Synced Realm - Kotlin SDKApp Services - Kotlin SDK →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.