Docs Menu
Docs Home
/ /
Atlas App Services

MongoDB Data Source Configuration Files

On this page

  • Service Configuration
  • MongoDB Clusters
  • Federated database instances
  • Databases & Collections
  • Collection Schema
  • Relationships
  • Default Rules
  • Collection Rules
  • Rule Configurations
  • Roles
  • Filters

Note

This page describes a legacy configuration file format. You should only use this information if you're using the deprecated realm-cli.

Any configuration files you pull with App Services CLI or export from the UI use the latest configuration version. For detailed information on the current configuration file format, see App Configuration.

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

Required. Default: mongodb-atlas

The service name used to refer to the cluster within this Atlas App Services 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
App Services routes all read operations to the current replica set primary node. This is the default read preference mode.
App Services 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.
App Services routes all read operations to one of the current replica set secondary nodes.
App Services 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.
App Services routes read operations to the replica set member that has the lowest network latency relative to the client.
config.wireProtocolEnabled
Boolean
/data_sources/<Service Name>/config.json
{
"name": "<Service Name>",
"type": "datalake",
"config": {
"dataLakeName": "<Federated database instance name>"
}
}
Field
Description
name
String

Required. Default: mongodb-datafederation

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

type
String
Required. For a Federated database instance, this value is always "datalake".
config.dataLakeName
String
Required. The name of the Federated database instance in Atlas.

If you want to enforce a schema for a collection, 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:

/data_sources/<data source>/<database>/<collection>/schema.json
{
"title": "<Object Type Name>",
"bsonType": "object",
"properties": {
"<Property Name>": { <Schema> },
...
}
}
/data_sources/<data source>/<database>/<collection>/relationships.json
{
"<Source Field Name>": {
"ref": "#/relationship/<Data Source Name>/<Database Name>/<Collection Name>",
"source_key": "<Source Field Name>",
"foreign_key": "<Foreign Field Name>",
"is_list": <Boolean>
},
...
}
Field
Description
ref
String

A JSON schema $ref string that specifies the foreign collection. The string has the following form:

#/relationship/<Data Source Name>/<Database Name>/<Collection Name>
source_key
String
The name of the field in this collection's schema that specifies which documents in the foreign collection to include in the relationship. A foreign document is included if source_key contains the value of its foreign_key field.
foreign_key
String
The name of the field in the foreign collection's schema that contains the value referenced by source_key.
is_list
Boolean

If true, the relationship may refer to multiple foreign documents (i.e. a "to-many" relationship). The source_key field must be an array with elements of the same type as the foreign_key field.

If false, the relationship may refer to zero or one foreign documents (i.e. a "to-one" relationship). The source_key field must be the same type as the foreign_key field.

Example

An ecommerce app defines a relationship between two collections: each document in store.orders references one or more documents in the store.items collection by including item _id values in the order's items array. Both collection are in the same linked cluster (mongodb-atlas) and database (store).

The relationship is defined for the orders collection:

/data_sources/mongodb-atlas/store/orders/relationships.json
{
"items": {
"ref": "#/relationship/mongodb-atlas/store/items",
"source_key": "items",
"foreign_key": "_id",
"is_list": true
}
}

You can define default rules that apply to all collections in a data source that don't have more specific collection-level rules defined.

You define default rules in the data source's default_rule.json configuration file at data_sources/<data-source-name>/default_rule.json.

/data_sources/<data source>/default_rule.json
{
"roles": [<Role>],
"filters": [<Filter>]
}
Field
Description
roles
Array<Role>
An array of Role configurations.
filters
Array<Filter>
An array of Filter configurations.

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

/data_sources/<data source>/<database>/<collection>/rules.json
{
"database": "<Database Name>",
"collection": "<Collection Name>",
"roles": [<Role>],
"filters": [<Filter>]
}
Field
Description
database
String
The name of the database that holds the collection.
collection
String
The name of the collection.
roles
Array<Role>
An array of Role configurations.
filters
Array<Filter>
An array of Filter configurations.
{
"name": "<Role Name>",
"apply_when": { Expression },
"document_filters": {
"read": { Expression },
"write": { Expression }
},
"read": { Expression },
"write": { Expression },
"insert": { Expression },
"delete": { Expression },
"search": <Boolean>,
"fields": {
"<Field Name>": {
"read": { Expression },
"write": { Expression },
"fields": { Embedded Fields }
},
...
},
"additional_fields": {
"read": { Expression },
"write": { Expression }
}
}
Field
Description
name
string
The name of the role. Role names identify and distinguish between roles in the same collection. Limited to 100 characters or fewer.
apply_when
object

An expression that evaluates to true when this role applies to a user.

When Device Sync (Flexible Mode) is not enabled, App Services assigns a role on a per-document basis. When Device Sync (Flexible Mode) is enabled, App Services assigns roles on a per-collection, per-session basis -- that is, for each synced collection when a client opens a sync connection.

To assign a role, App Services evaluates the apply_when of each potential role until one evaluates to true. Potential roles are any roles specified in the rules.json configuration file for the given collection or, if no rules.json file is found for the given collection, the default role(s). App Services evaluates roles in the order that you specify them in your configuration. If no role matches, then access is denied. For more information, see Role-based Permissions.

If Device Sync (Flexible Mode) is enabled, the assigned roles must be Sync compatible. If the role is not Sync compatible, but its apply_when evaluated to true, others roles are not considered; access is denied.

document_filters
Document
Default: undefined

A document with read and write expressions that determine whether the role's other permissions may be evaluated.

If Device Sync is enabled, both document_filters.read and document_filters.write must be defined to make the role Sync compatible. Sync incompatible roles deny all access to Sync requests.

If Device Sync is not enabled, document_filters, document_filters.read, and document_filters.write are all optional; an undefined document_filters.read or document_filters.write defaults to true, allowing subsequent permissions to be evaluated.

"document_filters": {
"read": { Expression },
"write": { Expression }
}
document_filters.read
object?
Default: undefined

An expression that specifies whether read, read permissions in fields, and read permissions in additional_fields may be evaluated. If false (and document_filters.write is undefined or false), read access is denied for the entire document.

To maintain Sync compatibility, the expression must be defined and may only reference queryable fields.

document_filters.write
object?
Default: undefined

An expression that specifies whether write, write permissions in fields, and write permissions in additional_fields may be evaluated. If false, then write access is denied for the entire document.

To maintain Sync compatibility, the expression must be defined and may only reference queryable fields.

read
object?
Default: undefined

An expression that evaluates to true if the role has permission to read all fields in the document.

To maintain Sync compatibility, the expression must be a boolean literal (either true or false).

Document-level read permissions take priority over any field-level permissions. If a role has document-level read permissions, it applies to all fields in the document. Read permissions specified by fields or additional_fields do not override document-level read permissions.

To define a default fallback alongside field-level rules, leave read undefined and use additional_fields.

write
object?
Default: undefined

An expression that evaluates to true if the role has permission to add, modify, or remove all fields in the document.

To maintain Sync compatibility, the expression must be a boolean literal (either true or false).

Document-level write permissions take priority over any field-level permissions. If a role has document-level write permissions, it applies to all fields in the document. Write permissions specified by fields or additional_fields do not override document-level write permissions.

To define a default fallback alongside field-level rules, leave write undefined and use additional_fields.

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

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.

insert
object?
Default: true

An expression that evaluates to true if the role has permission to insert a new document into the collection.

App Services only evaluates this expression for insert operations and only after determining that the role has write permission for all fields in the new document.

delete
object?
Default: true

An expression that evaluates to true if the role has permission to delete a document from the collection.

App Services only evaluates this expression for delete operations and only after determining that the role has write permission for all fields in the document to be deleted.

search
Boolean
Default: true

An expression that evaluates to true if the role has permission to search the collection using Atlas Search.

Important

App Services 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 each key corresponds to a field name, and each value defines the role's field-level read and write permissions for the corresponding field in a queried document.

To maintain Sync compatibility, the inner read and write expressions must be boolean literals (either true or false).

"fields": {
"<Field Name>": {
"read": { Expression },
"write": { 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
object?
Default: false

An expression that evaluates to true if the role has permission to read the field.

To maintain Sync compatibility, the expression must be a boolean literal (either true or false).

fields.<Field Name>.write
object?
Default: false

An expression that evaluates to true if the role has permission to add, modify, or remove the field.

To maintain Sync compatibility, the expression must be a boolean literal (either true or false).

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 in the fields document.

To maintain Sync compatibility, the inner read and write expressions must be boolean literals (either true or false).

"additional_fields": {
"read": { Expression },
"write": { Expression }
}
additional_fields.read
object?
Default: false

An expression that evaluates to true if the role has permission to read any field that does not have a field-level permission definition in fields.

To maintain Sync compatibility, the expression must be boolean (either true or false).

additional_fields.write
object?
Default: false

An 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 in fields.

To maintain Sync compatibility, the expression must be boolean (either true or false).

{
"name": "<Filter Name>",
"apply_when": { Expression },
"query": { MongoDB Query },
"projection": { MongoDB Projection }
}
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
object

An expression that determines when this filter applies to an incoming MongoDB operation.

Important

Atlas App Services 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 expansions like %%user, %%values, and %function.

query
object
Default: {}

A MongoDB query that App Services merges into a filtered operation's existing query.

Example

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

{ "score": { "$gte": 20 } }
projection
object
Default: {}

A MongoDB projection that App Services merges into a filtered operation's existing projection.

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 withholds the _internal field from all documents using the following projection:

{ "_internal": 0 }
What are the Atlas Application Services? →