• Realm >
• MongoDB Data Access >
• Configure a MongoDB Data Source

Link a MongoDB Data Source

Overview

You can use MongoDB Realm to work with a data source – either a MongoDB Atlas cluster or Data Lake associated with the same Atlas project as your Realm app. To connect to a data source through Realm, you must first link it to a new MongoDB service in your application.

You can create a MongoDB service and link a data source to your Realm app through the Realm UI or with an import/export configuration directory. Select the tab below that corresponds to the method you want to use.

Version 4.4 Required for Sync

In order to use Realm Sync, your Atlas cluster must use MongoDB version 4.4.

Procedure

• Realm UI
• Realm CLI

1

Navigate to the Data Source Management Screen

In the Realm UI, click Linked Data Sources under Manage in the left navigation menu.

2

Link a New Data Source

Click Link a Data Source and provide the following configuration information on the Data Source Configuration screen:

Field	Description
Data Source	A MongoDB Atlas cluster or Data Lake associated with the same project as your Realm app.
Realm Service Name	A name for the Realm service that connects to the data source. You will use this name when referring to the data source in other parts of your application, such as when you instantiate a MongoDB service client. Example Consider a MongoDB cluster data source with the Realm Service Name myAtlasCluster. To create a service client in a function you would use the following code: copy const myAtlasCluster = context.services.get("myAtlasCluster");
MongoDB Connection String config.wireProtocolEnabled	Required for Atlas clusters. Not enabled for Data Lakes. A boolean indicating whether Realm should allow clients to connect to this cluster with a connection string over the wire protocol.
Read Preference	Required for Atlas clusters. Not available for Data Lakes. Specifies the read preference of the cluster. The default read preference (primary) should be sufficient for most use cases.

3

Save the Linked Data Source

Once you’ve selected and configured a MongoDB cluster or Data Lake, click Save.

1

Export Your Realm Application

To link a MongoDB Atlas cluster to your Realm app with realm-cli, you need a previously created application configuration.

You can export your application from the Import/Export App tab of the Deploy page in the Realm UI, or by running the following command from an authenticated instance of realm-cli:

copy

realm-cli export --app-id=<App ID>

2

Create a MongoDB Service Configuration Directory

Create a new subdirectory in the /services folder of the application directory that you exported. The name of the subdirectory should match the name of the MongoDB service you’re creating.

copy

mkdir -p services/<MongoDB Service Name>

3

Add a MongoDB Service Configuration File

Add a file named config.json to the new service directory.

The configuration file to link an Atlas cluster should have the following form:

copy

config.json

{
  "id": "<Service ID>",
  "name": "<Service Name>",
  "type": "mongodb-atlas",
  "config": {
    "clusterName": "<Atlas Cluster Name>",
    "readPreference": "<Read Preference>",
    "wireProtocolEnabled": <Boolean>,
    "sync": <Sync Configuration>
  }
}

The configuration file to link a Data Lake should have the following form:

copy

config.json

{
  "id": "<Service ID>",
  "name": "<Service Name>",
  "type": "datalake",
  "config": {
     "dataLakeName": "<Data Lake>"
   }
 }

Exactly one of config.dataLakeName and config.clusterName is required, depending on whether you are linking a Data Lake or a cluster.

Field	Description
id String	A string that uniquely identifies the service. Realm automatically generates a unique ID for a MongoDB service when you create it.
name String	The name of the service. The name may be at most 64 characters long and can only contain ASCII letters, numbers, underscores, and hyphens. For clusters, the default name is mongodb-atlas. For Data Lakes, it is mongodb-datalake.
type String	For MongoDB Atlas clusters, this value is always "mongodb-atlas". For Data Lakes, this value is "datalake".
config.clusterName String	Required when linking a cluster. The name of the service’s linked cluster in MongoDB Atlas.
config.dataLakeName String	Required when linking a Data Lake. The name of the Data Lake that you want to link to your application.
config.readPreference String	The read preference mode for queries sent through the service. Not available for Data Lakes. Mode Description primary Realm routes all read operations to the current replica set primary node. This is the default read preference mode. primaryPreferred Realm routes all read operations to the current replica set primary node if it’s available. If the primary is unavailable, such as during an automatic failover, read requests are routed to a secondary node instead. secondary Realm routes all read operations to one of the current replica set secondary nodes. secondaryPreferred Realm routes all read operations to one of the replica set’s available secondary nodes. If no secondary is available, read requests are routed to the replica set primary instead. nearest Realm routes read operations to the replica set member that has the lowest network latency relative to the client.
config.sync Document	A configuration document that determines if a cluster is synced and, if it is, defines the rules for sync operations on the cluster. Not available for Data Lakes. For detailed information on sync configuration documents, see Synced Cluster Configuration.

4

Import the Application Directory

Once you’ve added the MongoDB service configuration, all that’s left is to import the function.

1. Save the config.json.

2. Navigate to the root of the exported application directory.

3. Log in to MongoDB Atlas with realm-cli:

   copy

   realm-cli login --api-key="<my api key>" --private-api-key="<my private api key>"
   

4. Import the directory:

   copy

   realm-cli import
   

Realm will immediately begin the process of linking to the data source, which could take up to five minutes. Once Realm is finished linking to the data source, you can start working with the data.

Linked Data Lake Considerations

For the most part, you can interact with a linked Data Lake just as you would with a linked Atlas cluster. However, there are some caveats to keep in mind when working with a Data Lake:

• Data Lakes do not support write operations.
• You can only access a linked Data Lake from a system function.
• You cannot connect to the Data Lake via the wire protocol.
• You cannot define roles and permissions for a linked Data Lake.
• You cannot set a Read Preference for a linked Data Lake.

Work with a Linked Data Source

The following pages demonstrate how to start working with your linked data source from a function:

See

• Insert Documents
• Find Documents
• Update Documents
• Delete Documents
• Run Aggregation Pipelines

You can access your MongoDB data source remotely from a client. See the following sections of the Client Guides:

See

• MongoDB Data Access (Android SDK)
• Remotely Access MongoDB (iOS SDK)
• MongoDB Data Access (Node SDK)
• MongoDB Data Access (React Native SDK)

←   MongoDB Atlas Overview Enforce a Document Schema  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.