Docs Menu

MongoDB Atlas Overviewicons/link.png

On this page

  • Overview
  • Get Started
  • CRUD & Aggregation Operations
  • Considerations
  • System-Generated Cluster Users
  • Accessing Application Data with Another Tool
  • Realm Sync Schema Data Consistency
  • Related Content
  • Configuration Guides
  • Usage Guides
  • Reference Documentation

MongoDB Realm provides a first-class service interface for MongoDB Atlas that enables secure querying of one or more Atlas data sources. You can use the Query API syntax to access your data directly in your client application code or from a Realm Function.

The MongoDB service secures your data with a dynamic, role-based Rules engine that proxies and modifies incoming queries based on rules that you define. There are three types of MongoDB collection rules: roles, filters, and schemas.

To get started with the MongoDB service, link a data source to your application and define roles and permissions for a collection. After you've created at least one role, you can start to work with data in the collection.

MongoDB Realm allows you to securely work with data in a MongoDB Atlas cluster directly from your client applications and Functions using standard, platform-idiomatic MongoDB query syntax. You can also access a linked MongoDB Atlas Data Lake from a system function.

The following guides demonstrate how to use MongoDB service actions to work with data in a linked data source:

Define Collection Rules

When working with a linked MongoDB Atlas cluster outside of a system function, MongoDB Realm dynamically determines which documents and fields in a collection each application user can read and write for all incoming query operations by evaluating collection rules that you define.

If you do not define rules for a collection, queries on the collection will fail.

Advanced MongoDB Queries

MongoDB Realm does not support all MongoDB CRUD and Aggregation operations when you query MongoDB as a specific user. You can bypass this limitation by querying MongoDB from a system function that runs as the system user, which has access to the full MongoDB CRUD and Aggregation APIs.

For more information on which operations are unsupported, see CRUD & Aggregation APIs.

MongoDB Realm 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 a Realm app, the associated user will also be deleted.

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

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

While running update operations, MongoDB Realm temporarily adds a reserved field, _id__baas_transaction, to documents. Once a document is successfully updated, MongoDB Realm 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 mongo shell to update documents in the products collection, your command might resemble the following code:

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

If the collection in which you create and modify objects is also accessed by Realm Sync clients, you must ensure that the data conforms to the Realm object schema defined on the collection. Consider the following scenario:

  • You have a collection of objects that is used by Realm Sync clients. The object schema for the collection looks like this:

    type Person = {
    _id: BSON.ObjectId;
    name: string;
    address: string;
    age: number;
  • Using a Realm client (say, MongoDB Compass), you create and insert a document into the collection. The age property of this document has a value of "forty two".
  • Because of MongoDB's flexible schema, there is no error when inserting the document. However, because the the Sync object schema defines the age property as type number, the object fails schema validation and is not pushed to Sync.
  • The collection is now divergent: Sync clients do not see the new document, but MongoDB Realm clients do.

The same scenario holds true if a valid document is modified outside of Realm Sync such that one or more properties no longer conform to the Sync schema.

Any document that fails the object schema validation is added to the __realm_sync.unsynced_documents collection (along with the reason for the failure) and will also be logged in the Realm UI Logs console. If there are 100,000 or more documents that can't be synced, the Realm app is paused.


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

If your data is used by Sync clients but can also be created or modified outside of Realm 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.
Learn how to connect a MongoDB Atlas cluster or Data Lake to your application.
Learn how to set up role based data access controls on your MongoDB collections.
Learn how to add additional query parameters to incoming queries to secure data and improve query efficiency.
Learn how to specify complex MongoDB collection rules by modifying the underlying configuration file directly in the Realm UI.
Learn how to specify which replica set members MongoDB Realm reads data from.
Learn how to enable connections to MongoDB Realm through standard MongoDB clients and drivers.
Learn how to insert one or more documents into a MongoDB collection.
Learn how to find documents in a collection, including patterns and operators that you can use to refine your query.
Learn how to update documents in a collection, including operators for manipulating specific fields.
Learn how to remove one or more documents from a MongoDB collection.
Learn how to execute an aggregation pipeline on a collection to calculate summary statistics and manipulate documents.
Learn how to execute an bulkWrite operation on a collection.
Learn how to connect to MongoDB through MongoDB Realm using standard MongoDB driver clients.
Look up detailed examples and parameters for all MongoDB service actions.
Look up the components of the connection strings used to connect to MongoDB Realm over the wire protocol.
Look up support for specific MongoDB client operations in MongoDB Realm.
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.