Flexible Sync
On this page
Overview
MongoDB Realm Flexible Sync lets you define a query in the client, and sync only the objects that match the query. With client-side subscriptions, client applications can:
- Maintain queries
- React to changes
- Add, change, or delete queries
Together with rules and permissions, Flexible Sync provides a powerful way to configure Sync around your business logic.
When a client makes a query, Realm searches the server-side data set for documents matching the query. Then, the sync engine applies a set of rules to determine which documents in the results set the user should be able to access. Realm returns only the matching documents where the user has read or read/write access, and assigns the user the appropriate permissions.
Client applications can add, update, or remove queries dynamically at run-time from the device.
Flexible Sync is currently in preview. We encourage you to try out the feature and give feedback, but please be aware that:
- Configuration details may change.
- SDK API implementation details may change.
We do not recommend using Flexible Sync in production applications while it is still in preview.
Enabling Flexible Sync in Your Realm Application requires the following:
- A non-sharded MongoDB Atlas cluster running MongoDB 5.0 or greater
- A Realm app without Partition-Based Sync enabled. While Flexible Sync is in preview, you cannot use Flexible Sync & Partition-Based Sync in the same Realm app.
Queryable Fields
When you configure Flexible Sync, you specify one or more fields from your Sync Schema that your client application can query.
In a task tracker app, you might set assignee or owner
as queryable fields. On the client side, you can then query for tasks
whose assignee or owner matches the logged-in user.
Queryable fields apply across all collections in a Realm app's Sync Schema. You can use rules and permissions to configure more granular access control on individual collections.
Eligible Field Types
Flexible Sync only supports top-level primitive fields with a scalar type as queryable fields. You can also include arrays of these primitives as queryable fields. Flexible Sync does not support embedded objects or arrays of objects as queryable fields.
For information on the queries you can perform on these fields, see: Flexible Sync RQL Limitations
Reserved Field Names
Realm reserves some keywords for the Realm Query Language and other purposes. You cannot use reserved keywords as field names.
Realm reserves the following keywords with any capitalization:
|
|
|
You cannot use descending, Descending, DESCENDING, or
DeScEnDiNG as a field name.
Realm also reserves the following keywords with the given exact capitalization:
|
|
|
You cannot use true or TRUE, since both capitalizations are
specifically reserved, but you can use True or tRUE as a field name.
Performance and Storage
Queryable fields use storage on the backing Atlas cluster. The more queryable fields you configure, the more storage you use on the backing cluster. You can configure up to 10 queryable fields per application for Flexible Sync.
Learn more about optimizing performance and storage when using Flexible Sync.
Get Started with Flexible Sync
Define a Schema
To use Flexible Sync, create a schema for your Realm app. The eligible fields in your schema become queryable fields you can select when you enable Flexible Sync.
If you're not yet ready to create a schema, you can manually define queryable fields with Development Mode.
Enable Sync
After you have defined a schema, or decided to create your data model on the client side and use Development Mode to define a schema, you can enable Flexible Sync.
During the process of enabling Sync, you select queryable fields and define roles that control how users can access your data.
Select Fields to Query
When you enable Flexible Sync, you can select queryable fields in two ways:
- If you have defined your schema, you can select queryable fields from eligible fields in your schema.
- If you are using Development Mode, you can type a queryable field name that matches an eligible field type in your client application.
You can configure up to 10 queryable fields per Realm app. These fields apply across all of the collections in your application.
Define Roles
When a user submits a query to the Realm app, Sync determines which role applies for the user.
Roles consist of:
- A role name
- A rule for when to apply the role
- Read and write permissions for users with the role
You can define multiple roles to tailor your access permissions for each collection. Collections can have more than one role, or none at all.
You can also create default roles, which do not apply to a specific collection. Instead, default roles apply to any collection where you do not define custom roles.
Create Queries in Your Client Application
With Flexible Sync enabled, you can start creating queries from your client application.
The MongoDB Realm SDKs provide methods to create, update, and remove queries from the client application. The SDKs use subscriptions to maintain those queries on the client side. Through these subscriptions, your applications sync objects with the backend Realm app and can watch for and react to changes.