Navigation

MongoDB Data Source Configuration Files

app/
└── data_sources/
└── <service name>/
├── config.json
└── <database>/
└── <collection>/
├── schema.json
└── rules.json
config.json
{
"name": "<Service Name>",
"type": "mongodb-atlas",
"config": {
"clusterName": "<Atlas Cluster Name>",
"readPreference": "<Read Preference>",
"sync": { <Sync Configuration> },
"wireProtocolEnabled": <Boolean>
}
}
Field
Description
name
String

Required. Default: mongodb-atlas

The service name used to refer to the cluster within this Realm app. The name may be at most 64 characters long and must only contain ASCII letters, numbers, underscores, and hyphens.

type
String
Required. For MongoDB Atlas clusters, this value is always "mongodb-atlas".
config.clusterName
String
Required. The name of the cluster in Atlas.
config.readPreference
String

The read preference mode for queries sent through the service.

Mode
Description
Realm routes all read operations to the current replica set primary node. This is the default read preference mode.
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.
Realm routes all read operations to one of the current replica set secondary nodes.
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.
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.

For detailed information on sync configuration documents, see Synced Cluster Configuration.

config.wireProtocolEnabled
Boolean

The config.sync field of config.json determines if a cluster is synced and, if it is, defines the rules for sync operations on the cluster.

config.json
{
...,
"config": {
...,
"sync": {
"state": <Boolean>,
"development_mode_enabled": <Boolean>,
"database_name": "<Developer Mode Database Name>",
"partition": {
"key": "<Partition Key Field Name>",
"type": "<Partition Key Value Type>",
"permissions": {
"read": <JSON Expression>,
"write": <JSON Expression>
}
}
}
}
}
Field
Description
sync.state
Boolean
If true, Sync is enabled for the cluster, which means that client applications can sync data in the cluster with Realm Database and that non-sync collection rules do not apply.
sync.development_mode_enabled
Boolean

If true, development mode is enabled for the cluster. While enabled, Realm automatically stores synced objects in a specific database within the cluster and mirrors objects types in that database's collection schemas.

Important

Realm does not enforce rules when development mode is enabled.

sync.database_name
String

The name of the database in the synced cluster where Realm should store synced objects.

When development mode is enabled, Realm stores synced objects in this database. Each object type maps to its own collection in the database with a schema that matches the synced objects.

sync.partition.key
String
The name of the field that partitions data into client Realms.
sync.partition.type
String
The type of the partition key field value.
sync.partition.permissions
Document
A document that defines the read and write permissions for the synced cluster. Permissions are defined with rule expressions that Realm evaluates per-user, per-partition. The expressions have access to the %%user and %%partition expansions.
/data_sources/<Service Name>/config.json
{
"name": "<Service Name>",
"type": "datalake",
"config": {
"dataLakeName": "<Data Lake>"
}
}
Field
Description
name
String

Required. Default: mongodb-datalake

The service name used to refer to the data lake within this Realm app. The name may be at most 64 characters long and must only contain ASCII letters, numbers, underscores, and hyphens.

type
String
Required. For MongoDB Atlas data lakes, this value is always "datalake".
config.dataLakeName
String
Required. The name of the data lake in Atlas.

If you want to enforce a document schema for a collection, you can define a schema.json configuration file that contains a JSON schema for the documents. The root level schema must be an object schema, which has the following form:

/<service>/<database>/<collection>/schema.json
{
"title": "<Object Type Name>",
"bsonType": "object",
"properties": {
"<Property Name>": { <Schema> },
...
}
}

If the data source is not a synced cluster or a data lake, then you can define collection-level rules in a collection's rules.json configuration file.

/data_sources/<service>/<database>/<collection>/rules.json
{
"database": "<Database Name>",
"collection": "<Collection Name>",
"roles": [<Query Role>],
"filters": [<Query Filter>]
}
Field
Description
database
String
The name of the database that holds the collection.
collection
String
The name of the collection.
roles
Array<Document>

An array of query role configuration documents, which have the following form:

{
"name": "<Role Name>",
"apply_when": <JSON Expression>,
"insert": <Boolean|JSON Expression>,
"delete": <Boolean|JSON Expression>,
"read": <Boolean|JSON Expression>,
"write": <Boolean|JSON Expression>,
"search": <Boolean|JSON Expression>,
"fields": {
"<Field Name>": {
"read": <Boolean|JSON Expression>,
"write": <Boolean|JSON Expression>,
"fields": <Fields Document>
},
...
},
"additional_fields": {
"read": <Boolean|JSON Expression>,
"write": <Boolean|JSON Expression>
},
}
Field
Description
name
String
The name of the role. Role names are useful for identifying and distinguishing between roles. Limited to 100 characters or fewer.
apply_when
Document
A JSON Expression that evaluates to true when this role should be applied.
read
Boolean or Document
Default: false

A boolean or JSON Expression that evaluates to true if the role has permission to read all fields in the document.

Document-level read permissions take priority over any field-level permissions. If a role has a document-level read rule, it applies to all fields in the document and cannot be overridden. To define specific field-level rules with a default fallback, use additional_fields instead.

write
Boolean or Document
Default: false

A boolean or JSON Expression that evaluates to true if the role has permission to add, modify, or remove all fields in the document.

Document-level write permissions take priority over any field-level permissions. If a role has a document-level write rule, it applies to all fields in the document and cannot be overridden. To define specific field-level rules with a default fallback, use additional_fields instead.

Important
Implicit Read Permission

Any time a role has write permission for a particular scope it also has read permission even if that is not explicitly defined.

Note
MongoDB Expansions

You can use MongoDB expansions, like %%root and %%prevRoot, in write JSON expressions.

insert
Boolean or Document
Default: true

A boolean or JSON Expression that evaluates to true if the role has permission to insert a new document into the collection.

Note

Document-level insert permission does not imply that a role can insert any document. The role must also have write permission for all fields in an inserted document for the insert to succeed.

delete
Boolean or Document
Default: true
A boolean or JSON Expression that evaluates to true if the role has permission to delete a document from the collection.
search
Boolean or Document
Default: true

A boolean or JSON Expression that evaluates to true if the role has permission to search the collection using Atlas Search.

Important

Realm performs $search operations as a system user and enforces field-level rules on the returned search results. This means that a user may search on a field for which they do not have read access. In this case, the search is based on the specified field but no returned documents include the field.

fields
Document
Default: {}

A document where the value of each field defines the role's field-level read and write permissions for the corresponding field in a queried document.

"fields": {
"<Field Name>": {
"read": <Boolean|JSON Expression>,
"write": <Boolean|JSON Expression>,
"fields": <Fields Document>
},
...
}
Note
Permission Priority

Document-level read or write permissions override all field-level permissions of the same type. If permissions are defined for a field that contains an embedded document, those permissions override any permissions defined for the document's embedded fields.

fields.<Field Name>.read
Boolean or Document
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to read the field.
fields.<Field Name>.write
Boolean or Document
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to add, modify, or remove the field.
fields.<Field Name>.fields
Document
Default: {}

A fields document that defines read and write permissions for fields that are embedded within this field in a queried document.

See the Field-level Permissions for Embedded Documents role pattern for more information.

additional_fields
Document
Default: {}

A document that defines the role's field-level read and write permissions for any fields in a queried document that don't have explicitly defined permissions.

"additional_fields": {
"read": <Boolean|JSON Expression>,
"write": <Boolean|JSON Expression>
}
additional_fields.read
Boolean or Document
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to read any field that does not have a field-level permission definition.
additional_fields.write
Boolean or Document
Default: false
A boolean or JSON Expression that evaluates to true if the role has permission to add, modify, or remove any field that does not have a field-level permission definition.
filters
Array<Document>

An array of query filter configuration documents, which have the following form:

{
"name": "<Filter Name>",
"apply_when": <JSON Expression>,
"query": <Query Document>,
"projection": <Projection Document>
}
Field
Description
name
String
Required. The name of the filter. Filter names are useful for identifying and distinguishing between filters. Limited to 100 characters or fewer.
apply_when

Required. A JSON expression that determines when this filter applies to a given query.

Important

MongoDB Realm evaluates and applies filters before it reads any documents, so you cannot use MongoDB document expansions in a filter's Apply When expression. However, you can use other expression variables, such as %%user, %%values, and %function.

query
Document

Required. A MongoDB query filter that contains additional query predicates to merge into incoming queries that the filter applies to.

Example

A filter that withholds documents that have a score below 20 could use the following filter query:

{ "score": { "$gt": 20 } }
projection
Document

Required. A MongoDB projection document that specifies additional field projections to merge into incoming queries that the filter applies to.

Important
Projection Conflicts

MongoDB projections can be either inclusive or exclusive, i.e. they can either return only specified fields or withhold fields that are not specified. If multiple filters apply to a query, the filters must all specify the same type of projection, or the query will fail.

Example

A filter that withholds the _internal field from all documents could use the following filter projection:

{ "_internal": 0 }
Give Feedback