Navigation

    MongoDB Atlas Overview

    MongoDB Realm provides a first-class service interface for MongoDB Atlas that lets you securely query one or more Atlas data sources. You can use standard MongoDB query language 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 Realm Schema.

    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:

    Important With Circle IconCreated with Sketch.Important
    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.

    Info With Circle IconCreated with Sketch.Note
    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.

    In traditional applications, an application server exposes an API to client applications and handles database queries on their behalf. To prevent malicious, improper, or incorrect read and write operations, clients don't query the database directly.

    MongoDB Realm provides a configurable and dynamic rules engine that enables you to run a MongoDB query from client applications while transparently preventing unauthorized reads and writes. Rules are defined for entire collections in a linked MongoDB Atlas cluster and apply to individual documents in the collection dynamically based on the application user that issued a query.

    Info With Circle IconCreated with Sketch.Note

    Data Lake data sources do not support rules. You can only access a Data Lake data source in a system function.

    The rules engine handles incoming queries with the following 4-step process:

    1

    MongoDB Realm evaluates the queried collection's Filters in the context of the incoming request. Filters dynamically add additional query predicates and projections to incoming queries based on an expression that you define.

    After evaluating, MongoDB Realm applies all relevant filters to the incoming query and then finds all documents that match the filtered query.

    Info With Circle IconCreated with Sketch.Note
    Query Filters

    To learn how to configure a query filter for a collection, see Filter Incoming Queries.

    To learn more about filters, explore the Query Filters reference page. There you'll find more information, including configuration parameters and details on how MongoDB Realm applies filters.

    2

    MongoDB Realm evaluates a Query Role with specific read and write permissions for each document that matches the filtered query. You define the roles for each collection, including the permissions they have and the conditions under which they apply.

    Info With Circle IconCreated with Sketch.Note
    Roles

    To learn how to configure roles for a collection, see Define Roles and Permissions.

    To learn more about roles, explore the Query Roles reference page. There you'll find more information, including configuration parameters, use-case examples, and details on how MongoDB Realm assigns roles to documents.

    3

    Once MongoDB Realm has evaluated a role for each document, it runs the filtered query and prevents reads and writes on each document unless the document's role allows them. If no role applies to a specific document, MongoDB Realm withholds that document entirely and prevents the query from reading or writing any fields.

    4

    If the query was a write operation, MongoDB Realm checks each affected document to ensure that they conform to the collection's Document Schema. If any document does not match the schema, MongoDB Realm rolls back the operation and rejects the query.

    Info With Circle IconCreated with Sketch.Note
    Document Schemas

    To learn how to configure a schema for documents in a collection, see Enforce a Document Schema.

    To learn more about schemas, explore the Document Schemas reference page. There you'll find more information, including schemas for common data types, configuration parameters, and details on how MongoDB Realm enforces document schemas.

    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_realm_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:

    db.products.update(
    { sku: "unknown" },
    { $unset: { _id_realm_transaction: "" } }
    )
    GuideDescription
    Link a MongoDB Data SourceLearn how to connect a MongoDB Atlas cluster or Data Lake to your application.
    Define Roles and PermissionsLearn how to set up role based data access controls on your MongoDB collections.
    Filter Incoming QueriesLearn how to add additional query parameters to incoming queries to secure data and improve query efficiency.
    Enforce a Document SchemaLearn how to specify a schema that controls the shape and contents of documents in a collection.
    Configure Advanced RulesLearn how to specify complex MongoDB collection rules by modifying the underlying configuration file directly in the Realm UI.
    Specify Cluster Read PreferenceLearn how to specify which replica set members MongoDB Realm reads data from.
    Enable Wire Protocol ConnectionsLearn how to enable connections to MongoDB Realm through standard MongoDB clients and drivers.
    GuideDescription
    Insert DocumentsLearn how to insert one or more documents into a MongoDB collection.
    Find DocumentsLearn how to find documents in a collection, including patterns and operators that you can use to refine your query.
    Update DocumentsLearn how to update documents in a collection, including operators for manipulating specific fields.
    Delete DocumentsLearn how to remove one or more documents from a MongoDB collection.
    Run Aggregation PipelinesLearn how to execute an aggregation pipeline on a collection to calculate summary statistics and manipulate documents.
    Bulk WritesLearn how to execute an bulkWrite operation on a collection.
    Connect Over the Wire ProtocolLearn how to connect to MongoDB through MongoDB Realm using standard MongoDB driver clients.
    GuideDescription
    MongoDB ActionsLook up detailed examples and parameters for all MongoDB service actions.
    Query RolesLearn how MongoDB Realm uses role-based permission sets to control CRUD permissions. See examples of Apply When and permission sets for common use cases.
    Query FiltersLearn how MongoDB Realm dynamically applies filters to optimize queries and secure data.
    Document SchemasLearn how MongoDB Realm uses JSON schemas to control and validate the shape and contents of documents in a collection.
    Connection StringsLook up the components of the connection strings used to connect to MongoDB Realm over the wire protocol.
    Service LimitationsLearn about MongoDB features that MongoDB Realm currently does not support and possible workarounds.
    CRUD & Aggregation APIsLook up support for specific MongoDB client operations in MongoDB Realm.
    Give Feedback