Write Data to a Synced Database

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:

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

What Data Syncs?

The subscription query combined with the permissions mean that the synced database 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 database.

Successful Writes

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

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, the SDK 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 database has no concept of "illegal" writes, the write initially succeeds until the SDK 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 database 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 database, 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.

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

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

Crashes Related to Opening a Synced Database in Multiple Processes

If you attempt to open a synced database in a Share Extension or other multiple-process use case, and that database is not already open in the main app, a write from a Share Extension may succeed. However, if the synced database 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 Database in Multiple Processes

If you need to read from or write to a synced database in more than one process, there are a few recommended alternatives:

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

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