Manage Flexible Sync Subscriptions - Swift SDK

Bootstrap the Realm with Initial Subscriptions

You must have at least one subscription before you can read from or write to the realm. You can bootstrap a realm with an initial subscription set when you open it with the flexibleSyncConfiguration(). Pass the initialSubscriptions parameter with the subscription queries you want to use to bootstrap the realm:

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

If your app needs to rerun this initial subscription every time the app starts, you can pass an additional parameter - rerunOnOpen. This is a bool that denotes whether the initial subscription should re-run every time the app starts. You might need to do this to re-run dynamic time ranges or other queries that require a re-computation of static variables for the subscription.

In this example, we don't want users to be overwhelmed by irrelevant tasks, so we'll load only tasks due within the previous 7 days and the next 7 days. Tasks that were due more than a week ago are no longer relevant, and tasks that are due further out than the next week are also not relevant. With rerunOnOpen here, the query dynamically recalculates the relevant objects to sync based on the desired date range every time the app starts.

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

Subscribe to All Objects of a Specific Type

In addition to syncing all objects that match a given query, you can subscribe to all objects of a specific type. You do this by appending a subscription without providing a query.

For example, if you don't want to see a specific team, but instead want to subscribe to all the Team objects, you could do this:

let subscriptions = realm.subscriptions
try await subscriptions.update {
    subscriptions.append(QuerySubscription<Team>(name: "all_teams"))
}

Check for Existing Subscriptions Before Adding a Subscription

If your application flow appends the same named subscription to the subscription set every time you run the application, this is disallowed. In this case, add a check for an existing subscription before appending it:

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

Pre Async/Await

If your application does not use Swift's async/await feature, you can react to subscription changes syncing with the server using the onComplete block. This block is called after subscriptions are synchronized with the server. If you want to react to subscription state changes by redrawing a UI, for example, or taking another action based on changes to the data set, take those actions in onComplete. This is also where you can handle optional errors that occur during synchronization.

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

Async/Await

If your application uses async/await, you don't need the onComplete block. The update executes asynchronously and throws an error if the update cannot complete successfully.

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

SyncSubscriptionState Enum

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

• Show a progress indicator while data is downloading
• Find out when a subscription set becomes superseded
• Wait for a subscription that has been persisted locally to sync with the server
• Watch for errors

Superseded

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.

Remove a Single Subscription

You can remove a specific subscription query in a subscription update block using remove. Specify the query by name or use the query as a string to find the appropriate subscription query to remove.

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

Remove All Subscriptions to an Object Type

If you want to remove all subscriptions to a specific object type, use the removeAll method with ofType in a subscription update block.

let subscriptions = realm.subscriptions
try await subscriptions.update {
    subscriptions.removeAll(ofType: Team.self)
}

Remove All Subscriptions

To remove all subscriptions from the subscription set, use the removeAll method in a subscription update block.

let subscriptions = realm.subscriptions
try await subscriptions.update {
    subscriptions.removeAll()
}