Navigation

Define Sync Rules

Info With Circle IconCreated with Sketch.Note

Realm Sync is currently in Beta.

MongoDB Realm enforces data access rules for all requests to a synced cluster. Sync rules are dynamic JSON expressions that specify a given user's ability to view and modify data in a synced partition.

Whenever a user opens a synced realm from a client app, Realm evaluates your app's rules and determines if the user has read and write permissions for the partition. Users must have read permission to sync and read data in a realm and must have write permission to create, modify, or delete objects. Write permission implies read permission, so if a user has write permission then they also have read permission.

Important With Circle IconCreated with Sketch.Important
Non-Sync Rules

This page describes data access rules for synced clusters. Non-synced cluster use a different rules model that sync rules override. If sync is enabled for a cluster, any non-sync rules defined for the cluster do not apply.

If your app does not use sync, check out MongoDB Collection Rules for more information on rules for non-synced clusters.

Sync rules apply to specific partitions and are coupled to your app's data model by the partition key. Consider the following behavior when designing your schemas to ensure that you have appropriate data access granularity and don't accidentally leak sensitive information.

  • Sync rules apply dynamically based on the user. One user may have full read & write access to a partition while another user has only read permissions or is unable to access the partition entirely. You control these permissions by defining JSON expressions.
  • Sync rules apply equally to all objects in a partition. If a user has read or write permission for a given partition then they can read or modify all synced fields of any object in the partition.
  • Write permissions require read permissions, so a user with write access to a partition also has read access regardless of the defined read permission rules.
Important With Circle IconCreated with Sketch.Important

You must define at least one valid schema for a collection in the synced cluster before you can define sync rules and enable sync.

At minimum, the schema must define _id and the field that you intend to use as your partition key. A partition key field may be a string, integer, or objectId.

For more details on how to define a schema, see Enforce a Document Schema.

1

To define sync rules and enable sync for your application, navigate to to the Sync configuration screen through the left navigation menu.

Info With Circle IconCreated with Sketch.Note
Sync Rules Cannot Change

You define sync rules at the same time as you enable sync. Once sync is enabled, you can't change your app's sync rules unless you terminate sync and re-enable it with new rules.

2

You can enable sync for a single linked cluster in your application. Determine which cluster you want to use and then select it from the Select Cluster To Sync dropdown menu.

The cluster selection dropown menu
3

The sync partition key is a field in every synced document that maps each document to a client-side realm. Sync rules apply at the partition level, so it's particularly important to consider your data model and access patterns. For more information on partition keys and how to choose one, see Partition Atlas Data into Realms.

Info With Circle IconCreated with Sketch.Note

The partition key can either be required or optional. If the partition key field is optional, then all MongoDB documents that either exclude the partition key or have a null value for the partition key will be sent to the null partition. If the partition key field is required, Realm Sync ignores any MongoDB documents that lack a valid value for the partition key. We recommend a required partition key unless you want to sync pre-existing data with invalid or missing partition values from a MongoDB collection.

Once you have decided which field to use, select it from the Choose A Partition Key dropdown menu.

The partition key selection dropdown menu
Info With Circle IconCreated with Sketch.Note

The partition key dropdown only lists fields defined in the cluster's schemas that would be valid partition keys.

If you don't see the field you want to use as the partition key listed, it probably means that your schema is invalid or that the field is not a string, integer, or objectId. You can check for schema errors on the Data Models tab of the SDKs screen.

4

The Define Permissions section allows you to define JSON expressions that Realm dynamically evaluates to determine a user's read and write permissions for the data in a given partition.

Sync rule expressions have access to %%user, which resolves to the user that opened the realm, and %%partition, which resolves to the partition key value for the realm. You can also use operators, including %function, to handle more complex cases. For examples, see Define Sync Permissions.

Once you've determined how to decide a user's read and write permissions for a given partition, define the corresponding JSON expressions in the Read and Write inputs.

The partition read and write expression inputs
5

Now that you've configured rules for your synced cluster, all that's left to do is turn on sync for client applications. Click Enable Sync, take note of any recommendations that appear, and then confirm your choice.

  • Sync rules allow you to control who can read and write data in a given realm.
  • You can define rules in the Realm UI or by importing them with Realm CLI.
Give Feedback