Write Data to a Synced Realm - Swift SDK

App Services Configuration

Device Sync is configured with the following queryable fields:

• _id (always included)

• complexity

• ownerId

The App Services App has permissions configured to let users read and write only their own data:

{
  "name": "owner-read-write",
  "apply_when": {},
  "document_filters": {
    "read": { "ownerId": "%%user.id" },
    "write": { "ownerId": "%%user.id" }
  },
  "read": true,
  "write": true
}

Client Data Model and Configuration

The examples on this page use the following object model:

class Item: Object {
    @Persisted(primaryKey: true) var _id: ObjectId
    @Persisted var ownerId: String
    @Persisted var itemName: String
    @Persisted var complexity: Int
}

Using that object model, the synced realm configuration syncs objects that match the subscription query where the complexity property's value is less than or equal to 4:

let app = App(id: YOUR_APP_ID_HERE)
do {
    let user = try await app.login(credentials: Credentials.anonymous)
    do {
        var flexSyncConfig = user.flexibleSyncConfiguration()
        flexSyncConfig.objectTypes = [Item.self]
        let realm = try await Realm(configuration: flexSyncConfig)
        let subscriptions = realm.subscriptions
        try await subscriptions.update {
            subscriptions.append(
                QuerySubscription<Item>(name: "simple-items") {
                 $0.complexity <= 4
            })
        }
        print("Successfully opened realm: \(realm)")
    } catch {
        print("Failed to open realm: \(error.localizedDescription)")
        // handle error
    }
} catch {
    fatalError("Login failed: \(error.localizedDescription)")
}

What Data Syncs?

The subscription query combined with the permissions mean that the synced realm only syncs objects where:

• The ownerId matches the user.id of the logged-in user (from the permissions)

• The complexity property's value is less than or equal to 4 (from the subscription query)

Any object in the Atlas collection where the ownerId does not match the user.id of the logged-in user, or the complexity property's value is greater than 4, cannot sync to this realm.

Successful Writes

When the write matches both the permissions and the Flexible Sync subscription query in the client, the Realm Swift SDK can successfully write the object to the synced realm. This object syncs with the App Services backend when the device has a network connection.

// This write falls within the subscription query and complies
// with the Device Sync permissions, so this write should succeed.
do {
    let learnRealm = Item()
    learnRealm.ownerId = user.id
    learnRealm.itemName = "Learn Realm CRUD stuff"
    learnRealm.complexity = 3
    try realm.write {
        realm.add(learnRealm)
    }
} catch {
    print("Failed to write to realm: \(error.localizedDescription)")
}

Compensating Writes

In some cases, a write that initially appears to succeed is actually an illegal write. In these cases, the object writes to the database, but when the database syncs to the backend, Realm reverts the write in a non-fatal error operation called a compensating write. Compensating writes can occur when:

• Writes don't match the query subscription: The written object matches the user's permissions, but does not match the query subscription.

• Writes don't match permissions: The written object matches the query subscription, but does not match the user's permissions.

In more detail, when you write data that is outside the bounds of a query subscription or does not match the user's permissions, the following occurs:

1. Because the client realm has no concept of "illegal" writes, the write initially succeeds until realm resolves the changeset with the App Services backend.

2. Upon sync, the server applies the rules and permissions. The server determines that the user does not have authorization to perform the write.

3. The server sends a revert operation, called a "compensating write", back to the client.

4. The client's realm reverts the illegal write operation.

Any client-side writes to a given object between an illegal write to that object and the corresponding compensating write will be lost.

In practice, this may look like an object being written to the realm, and then disappearing after the server sends the compensating write back to the client.

To learn more about permission denied errors, compensating write errors and other Device Sync error types, refer to Sync Errors in the App Services documentation.

The App Services logs contain more information about why a compensating write error occurs.

myApp.syncManager.errorHandler = { syncError, session in
    if let thisError = syncError as? SyncError {
        switch thisError.code {
        // ... additional SyncError.code cases ...
        case .writeRejected:
            if let compensatingWriteErrorInfo = thisError.compensatingWriteInfo {
                for anError in compensatingWriteErrorInfo {
                    print("A write was rejected with a compensating write error")
                    print("The write to object type: \(anError.objectType)")
                    print("With primary key of: \(anError.primaryKey)")
                    print("Was rejected because: \(anError.reason)")
                }
            }
        }
    }
}

A write was rejected with a compensating write error
The write to object type: Optional("Item")
With primary key of: objectId(641382026852d9220b2e2bbf)
Was rejected because: Optional("write to \"641382026852d9220b2e2bbf\" in table \"Item\" not
allowed; object is outside of the current query view")

do {
    let fixTheBug = Item()
    fixTheBug.ownerId = user.id
    fixTheBug.itemName = "Fix the bug with the failing method"
    // The complexity of this item is `7`. This is outside the bounds
    // of the subscription query, so this write triggers a compensating write.
    fixTheBug.complexity = 7
    try realm.write {
        realm.add(fixTheBug)
    }
} catch {
    print("Failed to write to realm: \(error.localizedDescription)")
}

Sync: Connection[1]: Session[1]: Received: ERROR "Client attempted a
write that is outside of permissions or query filters; it has been
reverted" (error_code=231, try_again=true, error_action=Warning)

"FlexibleSync_Item": {
    "63bdfc40f16be7b1e8c7e4b7": "write to \"63bdfc40f16be7b1e8c7e4b7\"
    in table \"FlexibleSync_Item\" not allowed; object is outside of
    the current query view"
}

do {
    let itemWithWrongOwner = Item()
    // The `ownerId` of this item does not match the `user.id` of the logged-in
    // user. The user does not have permissions to make this write, so
    // it triggers a compensating write.
    itemWithWrongOwner.ownerId = "This string does not match the user.id"
    itemWithWrongOwner.itemName = "Write code that generates a permission error"
    itemWithWrongOwner.complexity = 1
    try realm.write {
        realm.add(itemWithWrongOwner)
    }
} catch {
    print("Failed to write to realm: \(error.localizedDescription)")
}

Sync: Connection[1]: Session[1]: Received: ERROR "Client attempted a
write that is outside of permissions or query filters; it has been
reverted" (error_code=231, try_again=true, error_action=Warning)

"FlexibleSync_Item": {
    "63bdfc40f16be7b1e8c7e4b8": "write to \"63bdfc40f16be7b1e8c7e4b8\"
    in table \"FlexibleSync_Item\" was denied by write filter in role
    \"owner-read-write\""
}

Crashes Related to Opening a Synced Realm in Multiple Processes

If you attempt to open a synced realm in a Share Extension or other App Extension, and that realm is not open in the main app, a write from a Share Extension may succeed. However, if the synced realm is already open in the main app, or is syncing data in the background, you may see a crash related to Realm::MultiSyncAgents. In this scenario, you may need to restart the device.

Alternatives to Writing to a Synced Realm in an App Extension

If you need to read from or write to a synced realm from an App Extension, there are a few recommended alternatives:

• Offline-first: pass data on disk to or from the main app

• Always up-to-date: communicate directly with the backing Atlas collection across a network connection