Write Data to a Synced Realm - Kotlin SDK

App Services Configuration

Based on the above example object model, 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:

{
   "roles": [
      {
         "name": "readOwnWriteOwn",
         "apply_when": {},
         "document_filters": {
            "write": {
               "ownerId": "%%user.id"
            },
            "read": {
               "ownerId": "%%user.id"
            }
         },
         "read": true,
         "write": true,
         "insert": true,
         "delete": true,
         "search": true
      }
   ]
}

Any object in the Atlas collection where the ownerId does not match the user.id of the logged-in user cannot sync to this realm.

Client Data Model and Configuration

Using the object model, the examples configure the synced realm to synchronize objects matching this subscription query:

val app = App.create(FLEXIBLE_APP_ID)
val user = app.login(credentials)
val flexSyncConfig = SyncConfiguration.Builder(user, setOf(Item::class))
    // Add subscription
    .initialSubscriptions { realm ->
        add(
            // Get Items from Atlas that match the Realm Query Language query.
            // Uses the queryable field `complexity`.
            // Query matches objects with complexity less than or equal to 4.
            realm.query<Item>("complexity <= 4"),
            "simple-items"
        )
    }
    .build()
val syncRealm = Realm.open(flexSyncConfig)
syncRealm.subscriptions.waitForSynchronization()
Log.v("Successfully opened realm: ${syncRealm.configuration}")

Any object in the Atlas collection where the complexity property's value is greater than 4 cannot sync to this realm.

Successful Writes

When the write matches both user permissions and the query subscription in the client, the Realm Kotlin 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.

// Per the Device Sync permissions, users can only read and write data
// where the `Item.ownerId` property matches their own user ID.
val userId = user.id
val newItem = Item().apply {
    ownerId = userId
    itemName = "This item meets sync criteria"
    complexity = 3
}
syncRealm.write {
    // `newItem` is successfully written to the realm and synced to Atlas
    // because its data matches the subscription query (complexity <= 4)
    // and its `ownerId` field matches the user ID.
    copyToRealm(newItem)
}

Compensating Writes

When the write doesn't match either the query subscription or user permissions, Realm reverts the write and throws a CompensatingWriteException.

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 the write succeeding, but then the object "disappears" when Realm syncs with the App Services backend and performs the compensating write.

When this occurs, you can refer to the App Services logs or use the CompensatingWriteInfo object in the client to get additional information on the error.

// The complexity of this item is `7`. This is outside the bounds
// of the subscription query, which triggers a compensating write.
val itemTooComplex = Item().apply {
    ownerId = user.id
    itemName = "This item is too complex"
    complexity = 7
}
syncRealm.write {
    copyToRealm(itemTooComplex)
}

[Session][CompensatingWrite(231)] Client attempted a write that is disallowed by permissions, or modifies an object outside the current query, and the server undid the change.

Error:
Client attempted a write that is outside of permissions or query filters; it has been reverted (ProtocolErrorCode=231)
Details:
{
   "Item": {
      "63bdfc40f16be7b1e8c7e4b7": "write to \"63bdfc40f16be7b1e8c7e4b7\"
      in table \"Item\" not allowed; object is outside of
      the current query view"
   }
}

// 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, which
// triggers a compensating write.
val itemWithWrongOwner = Item().apply {
    ownerId = "not the current user"
    itemName = "A simple item"
    complexity = 1
}
syncRealm.write {
    copyToRealm(itemWithWrongOwner)
}

[Session][CompensatingWrite(231)] Client attempted a write that is disallowed by permissions, or modifies an object outside the current query, and the server undid the change.

Error:
Client attempted a write that is outside of permissions or query filters; it has been reverted (ProtocolErrorCode=231)
Details:
{
   "Item": {
      "63bdfc40f16be7b1e8c7e4b7": "write to \"63bdfc40f16be7b1e8c7e4b7\"
      in table \"Item\" was denied by write filter in role \"readOwnWriteOwn\""
   }
}

val syncErrorHandler = SyncSession.ErrorHandler { session, error ->
    runBlocking {
        if (error is CompensatingWriteException) {
            error.writes.forEach { writeInfo ->
                val errorMessage = """
                    A write was rejected with a compensating write error
                    The write to object type: ${writeInfo.objectType}
                    With primary key of: ${writeInfo.primaryKey}
                    Was rejected because: ${writeInfo.reason}
                    """.trimIndent()
                Log.e(errorMessage)
            }
        }
    }
}

A write was rejected with a compensating write error
The write to object type: Item
With primary key of: RealmAny{type=OBJECT_ID, value=BsonObjectId(649f2c38835cc0346b861b74)}
Was rejected because: write to "649f2c38835cc0346b861b74" in table "Item" not allowed; object is outside of the current query view