Docs Menu

Docs HomeAtlas App Services

Internal Database Usage

Atlas App Services uses your linked MongoDB Atlas cluster to manage some internal operations. In general, you do not need to know about these operations to use App Services.

App Services automatically creates a MongoDB user for each app linked to a cluster. These users are for internal use only and cannot be edited or manually deleted. If you delete an App, the associated user will also be deleted.

Users generated by App Services have names of the form: mongodb-realm-<your app id>

App Services connects to standard MongoDB Atlas clusters, which means that you can connect directly to a linked cluster using another tool such as the mongosh shell or MongoDB Compass. There are no special considerations when reading data from a linked cluster with another tool.

While running update operations, App Services temporarily adds a reserved field, _id__baas_transaction, to documents. Once a document is successfully updated, App Services removes this field. If you want to use another tool to modify data in a collection, ensure that you $unset this field prior to making changes.

For example, if you are using the mongosh shell to update documents in the products collection, your command might resemble the following code:

{ sku: "unknown" },
{ $unset: { _id__baas_transaction: "" } }

If a document in a synced collection does not conform to the collection's schema, it cannot be synced to client apps. If there are 100,000 or more unsyncable documents, App Services pauses sync for the app.

App Services stores a information about unsyncable documents in the __realm_sync.unsynced_documents collection.


You can read from the __realm_sync.unsynced_documents collection, but you should not modify it in any way.

A common cause for unsyncable documents is data added or modified outside of the context of your app.

Consider the following scenario:

  1. An app has a pets collection with the following schema:

    "title": "Pet",
    "required": ["_id", "type", "name", "age"],
    "properties": {
    "_id": { "bsonType: "objectId" },
    "type": { "bsonType: "string" },
    "name": { "bsonType: "string" },
    "age": { "bsonType: "int" }
  2. Someone adds a document directly to the pets collection using a MongoDB driver, MongoDB compass, or an Atlas Function running in "system" mode. The document's age field contains a string, not a number, which does not match your app's schema. MongoDB does not natively enforce your app's schema, so it allows the insert without a warning or error.

    "_id": "5ae782e48f25b9dc5c51c4a5",
    "type": "dog",
    "name": "Fido",
    "age": "7"
  3. Once inserted, the document fails schema validation in your app and cannot be synced. The app stores the failure in the unsynced_documents collection:

    "_id": "6183021879247167daacd8dc",
    "appId": "6183021373247568dcdcd3ed",
    "documentId": "5ae782e48f25b9dc5c51c4a5",
    "ns": {
    "db": "myDatabase",
    "coll": "pets"
    "reason": "invalid schema"
If your data is used by Sync clients but can also be created or modified outside of Atlas Device Sync, you must ensure those creations and modifications match the defined object schema on the collection. For documents that have failed, you can replace, update, or delete & re-add each document.
← Document Preimages