Write Data to a Synced Realm - C++ 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.identifier() of the logged-in user cannot sync to this realm.

Client Data Model and Configuration

The examples on this page use the following synced realm configuration with this sync query and object model:

With this Sync query, 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 C++ 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.
auto simpleItem =
    realm::Item{.ownerId = user.identifier(),
                          .itemName = "This item meets sync criteria",
                          .complexity = 3};
// `simpleItem` successfully writes to the realm and syncs to Atlas
// because its data matches the subscription query (complexity <= 4)
// and its `ownerId` field matches the user ID.
syncRealm.write([&] { syncRealm.add(std::move(simpleItem)); });

Compensating Writes

When the write doesn't match either the query subscription or user permissions, Realm reverts the write and provides an array of compensating_write_error_info objects.

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 compensating_writes_info() function in the client to get additional information on the error. For more information, refer to the Compensating Write Error Information section on this page.

// The complexity of this item is `7`. This is outside the bounds
// of the subscription query, which triggers a compensating write.
auto complexItem =
    realm::Item{._id = primaryKey,
                          .ownerId = user.identifier(),
                          .itemName = "Test compensating writes",
                          .complexity = 7};
// This should trigger a compensating write error when it tries to sync
// due to server-side permissions, which gets logged with the error handler.
syncRealm.write([&] { syncRealm.add(std::move(complexItem)); });

Connection[2]: Session[10]: Received: ERROR "Client attempted a write that is not allowed; it has been reverted" (error_code=231, is_fatal=false, error_action=Warning)

Error:
Client attempted a write that is not allowed; it has been reverted (ProtocolErrorCode=231)
Details:
{
   "Item": {
      "ObjectID(\"6557ddb0bf050934870ca0f5\")": "write to ObjectID(\"6557ddb0bf050934870ca0f5\")
      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.
auto itemWithWrongOwner = realm::Item{
    .ownerId = "not the current user",
    .itemName = "Trigger an incorrect permissions compensating write",
    .complexity = 1};
syncRealm.write([&] { syncRealm.add(std::move(itemWithWrongOwner)); });

Connection[2]: Session[11]: Received: ERROR "Client attempted a write that is not allowed; it has been reverted" (error_code=231, is_fatal=false, error_action=Warning)

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

auto info = receivedSyncError.compensating_writes_info();
for (auto &v : info) {
  std::cout << "A write was rejected with a compensating write error.\n";
  std::cout << "An object of type " << v.object_name << "\n";
  std::cout << "was rejected because " << v.reason << ".\n";
}

A write was rejected with a compensating write error.
An object of type Item
was rejected because write to ObjectID("6557ddb0bf050934870ca0f5") in
table "Item" not allowed; object is outside of the current query view.