Flexible Sync
On this page
Overview
Atlas App Services 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.
For a guide to setting up flexible sync with common permissions models, see Flexible Sync Permissions Guide.
When a client makes a query, App Services 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. App Services 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.
Enabling Flexible Sync in Your App Services Application requires a non-sharded MongoDB Atlas cluster running MongoDB 5.0 or greater
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 an 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
App Services reserves some keywords for the Realm Query Language and other purposes. You cannot use reserved keywords as field names.
App Services reserves the following keywords with any capitalization:
|
|
|
You cannot use descending, Descending, DESCENDING, or
DeScEnDiNG as a field name.
App Services 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 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 App. These fields apply across all of the collections in your application.
Define Roles
When a user submits a query to the 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 Atlas App Services 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 App and can watch for and react to changes.
Optimize Sync with Asymmetric Sync (Optional)
Asymmetric Sync is a sync strategy that is optimized for applications with heavy client-side insert-only workloads. You enable it for one or more collections. It supports writing to any collection type, including an Atlas time-series collection.
Asymmetric Sync is a feature of Flexible Sync and cannot be enabled on apps that use Partition-Based Sync.
For example, an IoT app that frequently logs sensor data has a significant write workload and no read workload. The device may also be offline for extended periods of time. Asymmetric Sync bypasses some of the processing required for bi-directional sync, significantly improving write speed to an Atlas collection.
Other use cases include writing immutable data, such as invoices from a retail app, or logging application events, neither of which requires conflict resolution.
You can apply Asymmetric Sync to individual collections. This means your app can use Asymmetric Sync to write some data, but bi-directional Flexible Sync on other collections.
Asymmetric Sync collections are only for writing data. You cannot use Flexible Sync queries against these collections. Instead, use MongoDB Data Sources.
You configure and enable Asymmetric Sync in the Advanced Options section of the Sync set up page. For more information on setting up Flexible Sync with Asymmetric Sync, see Enable Flexible Sync.
After you have enabled Asymmetric Sync, you implement it in the client app via the client SDKs.
The JavaScript SDK supports Asymmetric Sync. Support in the other SDKs is forthcoming.