Manage Flexible Sync Subscriptions - Swift 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, note the following if you use relationships or asymmetric objects in your app:

Permissions

Subscriptions work hand-in-hand with permissions to determine what data to Sync to your client application. The client application only sees the subset of data that matches your subscriptions which also matches the permissions of the logged-in user.

This page details how to manage client subscriptions for Flexible Sync. For information about setting up permissions for Flexible Sync, see: Flexible Sync Rules & Permissions.

Subscribe to a Query

With an authenticated user and a Flexible Sync configuration, you can open a synced realm and query for the objects you want to read and write. You can .subscribe() to that query to create a Flexible Sync subscription for objects matching the query:

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Task.self)
    .where { $0.progressMinutes >= 60 }.subscribe()
// Go on to work with subscribed results

This creates an unnamed subscription and adds it to the MutableSubscriptionSet, similar to manually creating a subscription.

Subscribe to a Query with a Subscription Name

If your app works with multiple subscriptions, or if you want to update a subscription, you may want to add a name when you subscribe to a query.

You can later use this name to update a subscription's query, check for a subscription by name, or remove the query by name.

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

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 a subscription should waitForSync:

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Team.self)
    .where { $0.members.contains("Bob Smith") }
    .subscribe(
        name: "bob_smith_teams",
        waitForSync: .onCreation)
// After waiting for sync, the results set contains all the objects
// that match the query - in our case, 1
print("The number of teams that have Bob Smith as a member is \(results.count)")

This option uses the RLMWaitForSyncMode enum, whose cases are:

• .onCreation: Wait to download matching objects when your app creates the subscription. Otherwise, return without waiting for new downloads. The app must have an internet connection the first time you add the subscription.

• .always: Wait to download matching objects when .subscribe() is executed. The app must have an internet connection when .subscribe() is executed.

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

You can optionally specify a timeout value of type TimeInterval.

Unsubscribe from a Query

You can unsubscribe from a query's Results set using the .unsubscribe() API:

let realm = try await Realm(configuration: flexSyncConfig)
let results = try await realm.objects(Task.self).where { $0.completed == false }.subscribe()
// Go on to work with subscribed results.
// Later...
results.unsubscribe()

This removes the subscription from the MutableSubscriptionSet, similar to manually removing a subscription.

A Results set may still contain objects after calling .unsubscribe() if another subscription exists that contains overlapping objects.

Calling .unsubscribe() does not wait for objects to be removed from the realm. There is no API to wait for .unsubscribe() to sync with the server.

Subscribe to an Actor-Confined Query

You can subscribe to an actor-confined query on the MainActor:

let realm = try await Realm(configuration: flexSyncConfig, actor: MainActor.shared)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

Or subscribe to a query on a custom actor:

let realm = try await Realm(configuration: flexSyncConfig, actor: CustomGlobalActor.shared)
let results = try await realm.objects(Team.self)
    .where { $0.teamName == "Developer Education" }
    .subscribe(name: "team_developer_education")
// Go on to work with subscribed results

For more information about actor-confined realms, refer to Use Realm with Actors - Swift SDK.

Add a Subscription

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

let realm = try await getRealmWithSingleSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithSingleSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
       subscriptions.append(
          QuerySubscription<Team> {
             $0.teamName == "Developer Education"
          })
    }
    return realm
}

You can add multiple subscriptions within a subscription update block, including subscriptions of different object types.

let realm = try await getRealmWithMultipleSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithMultipleSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.append(
            QuerySubscription<Task>(name: "completed-tasks") {
                 $0.completed == true
        })
        subscriptions.append(
            QuerySubscription<Team> {
              $0.teamName == "Developer Education"
        })
    }
    return realm
}

var flexSyncConfig = user.flexibleSyncConfiguration(initialSubscriptions: { subs in
    subs.append(
        QuerySubscription<Team> {
               $0.teamName == "Developer Education"
            })
})

// Set the date a week ago and the date a week from now, as those are the dates we'll use
// in the Flexible Sync query. `rerunOnOpen` lets the app recalculate this query every
// time the app opens.
let secondsInAWeek: TimeInterval = 604800
let dateLastWeek = (Date.now - secondsInAWeek)
let dateNextWeek = (Date.now + secondsInAWeek)
var flexSyncConfig = user.flexibleSyncConfiguration(initialSubscriptions: { subs in
    subs.append(
        QuerySubscription<Task> {
            $0.dueDate > dateLastWeek && $0.dueDate < dateNextWeek
        })
}, rerunOnOpen: true)

let realm = try await subscribeToObjectsOfAType()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func subscribeToObjectsOfAType() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.append(QuerySubscription<Team>(name: "all_teams"))
    }
    XCTAssertEqual(subscriptions.count, 1) // :remove
    return realm
}

let realm = try await checkAndAddSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func checkAndAddSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    let foundSubscription = subscriptions.first(named: "user_team")
    try await subscriptions.update {
        if foundSubscription != nil {
            foundSubscription!.updateQuery(toType: Team.self, where: {
                 $0.teamName == "Developer Education"
            })
        } else {
            subscriptions.append(
                QuerySubscription<Team>(name: "user_team") {
                  $0.teamName == "Developer Education"
               })
        }
    }
    return realm
}

Wait for Subscription Changes to Sync

Updating the subscription set locally is only one component 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.

let subscriptions = realm.subscriptions
subscriptions.update({
   subscriptions.append(
      QuerySubscription<Task> {
         $0.assignee == "John Doe"
      })
}, onComplete: { error in // error is optional
    if error == nil {
       // Flexible Sync has updated data to match the subscription
    } else {
       // Handle the error
    }
 })

@MainActor
func changeSubscription() async throws {
   let subscriptions = realm.subscriptions
   try await subcriptions.update {
      subscriptions.remove {
         QuerySubscription<Task> {
            $0.assignee == "Joe Doe"
         }
      }
   }
}

Subscription Set State

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

The superseded state is a SyncSubscriptionState 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.

Update Subscriptions with a New Query

You can update a subscription's query using updateQuery. In this example, we search for a subscription matching our query and then update it with a new query.

let realm = try await getRealmWithUpdatedSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithUpdatedSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        if let foundSubscription = subscriptions.first(ofType: Team.self, where: {
            $0.teamName == "Developer Education"
        }) {
            foundSubscription.updateQuery(toType: Team.self, where: {
                $0.teamName == "Documentation"
            })
        }
    }
    return realm
}

You can also search for a subscription by name . In this example, we search for a subscription query by name and then update it with a new query.

let realm = try await getRealmWithUpdatedSubscriptionName()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmWithUpdatedSubscriptionName() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    let foundSubscription = subscriptions.first(named: "user-team")
    try await subscriptions.update {
        foundSubscription?.updateQuery(toType: Team.self, where: {
             $0.teamName == "Documentation"
        })
    }
    return realm
}

Remove Subscriptions

To remove subscriptions, you can:

• Remove a single subscription query

• Remove all subscriptions to a specific object type

• Remove all unnamed subscriptions

• Remove all subscriptions

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

let realm = try await getRealmAfterRemovingSubscription()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingSubscription() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    // Look for a specific subscription, and then remove it
    let foundSubscription = subscriptions.first(named: "docs-team")
    try await subscriptions.update {
        subscriptions.remove(foundSubscription!)
    }
    // Or remove a subscription that you know exists without querying for it
    try await subscriptions.update {
        subscriptions.remove(named: "existing-subscription")
    }
    return realm
}

let realm = try await getRealmAfterRemovingAllSubscriptionsToAnObjectType()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingAllSubscriptionsToAnObjectType() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.removeAll(ofType: Team.self)
    }
    return realm
}

let realm = try await Realm(configuration: flexSyncConfig)
// Add 2 subscriptions, one named and one unnamed.
let results = try await realm.objects(Team.self).where { $0.teamName == "Developer Education" }.subscribe(name: "team_developer_education")
let results2 = try await realm.objects(Task.self).where { $0.completed == false }.subscribe()
// Later, remove only the unnamed one
let subscriptions = realm.subscriptions
try await subscriptions.update {
    subscriptions.removeAll(unnamedOnly: true)
}

let realm = try await getRealmAfterRemovingAllSubscriptions()
// Opening a realm and accessing it must be done from the same thread.
// Marking this function as `@MainActor` avoids threading-related issues.
@MainActor
func getRealmAfterRemovingAllSubscriptions() async throws -> Realm {
    let realm = try await Realm(configuration: flexSyncConfig)
    let subscriptions = realm.subscriptions
    try await subscriptions.update {
        subscriptions.removeAll()
    }
    return realm
}

API Efficiency

Adding several subscriptions with the .subscribe() and .unsubscribe() APIs described in the Subscribe to Queries section is less efficient than performing batch updates when you manually manage subscriptions. On every .subscribe(), the Swift SDK opens a new update block. For better performance adding multiple subscriptions, 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.

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